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 2021-03-03 01:44:47 +00:00
parent 7269d98b74
commit c3d9302930
26 changed files with 799 additions and 936 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

395
docs/master/getting-started/compose-infrastructure.md
View File

@ -1,395 +0,0 @@
---
title: Compose Infrastructure
toc: true
weight: 4
indent: true
---
# Compose Infrastructure
In the [last section] we learned that Crossplane can be extended by installing
_providers_, which add support for managed resources. A managed resource is a
Kubernetes custom resource that offers a high fidelity representation of an
infrastructure primitive, like an SQL instance or a firewall rule. Crossplane
goes beyond simply modelling infrastructure primitives as custom resources - it
enables you to define new custom resources with schemas of your choosing. These
resources are composed of managed resources, allowing you to define and offer
resources that group and abstract infrastructure primitives. We call these
"composite resources" (XRs).
XRs are always cluster scoped - they exist outside of any namespace. This allows
an XR to represent infrastructure that might be consumed from several different
namespaces. This is often true for VPC networks - an infrastructure operator may
wish to define a VPC network XR and an SQL instance XR, only the latter of which
may be managed by application operators. The application operators are
restricted to their team's namespace, but their SQL instances should all be
attached to the VPC network that the infrastructure operator manages. Crossplane
enables scenarios like this by allowing the infrastructure operator to offer
their application operators a _composite resource claim_ (XRC). An XRC is a
namespaced proxy for an XR; the schema of an XRC is identical to that of its
corresponding XR. When an application operator creates an XRC, a corresponding
backing XR is created automatically.
We use two special Crossplane resources to define and configure new XRs and
XRCs:
- A `CompositeResourceDefinition` (XRD) _defines_ a new kind of composite
resource, including its schema. An XRD may optionally _offer_ a claim.
- A `Composition` specifies which resources a composite resource will be
composed of, and how they should be configured. You can create multiple
`Composition` options for each composite resource.
XRDs and Compositions may be packaged and installed as a _configuration_. A
configuration is a [package] of composition configuration that can easily be
installed to Crossplane by creating a declarative `Configuration` resource, or
by using `kubectl crossplane install configuration`. In the examples below we
will install a configuration that defines a new `CompositePostgreSQLInstance` XR
that takes a single `storageGB` parameter, and creates a connection `Secret`
with keys for `username`, `password`, and `endpoint`. A `Configuration` exists
for each provider that can satisfy a `PostgreSQLInstance`. Let's get started!
## Configure and Claim Your Infrastructure
We will now install a `Configuration` that:
- Defines a `CompositePostgreSQLInstance` XR.
- Offers a `PostgreSQLInstance` claim (XRC) for said XR.
- Creates a `Composition` that can satisfy our XR.
<ul class="nav nav-tabs">
<li class="active"><a href="#aws-tab-1" data-toggle="tab">AWS (Default VPC)</a></li>
<li><a href="#aws-new-tab-1" data-toggle="tab">AWS (New VPC)</a></li>
<li><a href="#gcp-tab-1" data-toggle="tab">GCP</a></li>
<li><a href="#azure-tab-1" data-toggle="tab">Azure</a></li>
<li><a href="#alibaba-tab-1" data-toggle="tab">Alibaba</a></li>
</ul>
<br>
<div class="tab-content">
<div class="tab-pane fade in active" id="aws-tab-1" markdown="1">
> Note that this configuration will create an RDS instance using your default
> VPC, which may or may not allow connections from the internet depending on how
> it is configured. Select the AWS (New VPC) configuration if you wish to create
> an RDS instance that will allow traffic from the internet.
```console
kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-aws:latest
```
</div>
<div class="tab-pane fade" id="aws-new-tab-1" markdown="1">
> Note that this configuration for AWS also includes several networking managed
> resources that are required to provision a publicly available PostgreSQL
> instance. Composition enables scenarios such as this, as well as far more
> complex ones. See the [composition] documentation for more information.
```console
kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-aws-with-vpc:latest
```
</div>
<div class="tab-pane fade" id="gcp-tab-1" markdown="1">
```console
kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-gcp:latest
```
</div>
<div class="tab-pane fade" id="azure-tab-1" markdown="1">
```console
kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-azure:latest
```
</div>
<div class="tab-pane fade" id="alibaba-tab-1" markdown="1">
```console
kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-alibaba:latest
```
</div>
</div>
Crossplane should now be configured to allow us to create a `PostgreSQLInstance`
claim! You can watch the installation progress of the `Configuration` object by
running:
```console
kubectl get configuration --watch
```
Make sure you've [setup] a `ProviderConfig` named `default` for your chosen
provider, then create your XRC to provision a PostgreSQL instance and all the
supporting infrastructure (VPCs, firewall rules, resource groups, etc) that it
may need!
<ul class="nav nav-tabs">
<li class="active"><a href="#aws-tab-2" data-toggle="tab">AWS (Default VPC)</a></li>
<li><a href="#aws-new-tab-2" data-toggle="tab">AWS (New VPC)</a></li>
<li><a href="#gcp-tab-2" data-toggle="tab">GCP</a></li>
<li><a href="#azure-tab-2" data-toggle="tab">Azure</a></li>
<li><a href="#alibaba-tab-2" data-toggle="tab">Alibaba</a></li>
</ul>
<br>
<div class="tab-content">
<div class="tab-pane fade in active" id="aws-tab-2" markdown="1">
```yaml
apiVersion: database.example.org/v1alpha1
kind: PostgreSQLInstance
metadata:
name: my-db
namespace: default
spec:
parameters:
storageGB: 20
compositionSelector:
matchLabels:
provider: aws
vpc: default
writeConnectionSecretToRef:
name: db-conn
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-aws.yaml
```
</div>
<div class="tab-pane fade" id="aws-new-tab-2" markdown="1">
```yaml
apiVersion: database.example.org/v1alpha1
kind: PostgreSQLInstance
metadata:
name: my-db
namespace: default
spec:
parameters:
storageGB: 20
compositionSelector:
matchLabels:
provider: aws
vpc: new
writeConnectionSecretToRef:
name: db-conn
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-aws.yaml
```
</div>
<div class="tab-pane fade" id="gcp-tab-2" markdown="1">
```yaml
apiVersion: database.example.org/v1alpha1
kind: PostgreSQLInstance
metadata:
name: my-db
namespace: default
spec:
parameters:
storageGB: 20
compositionSelector:
matchLabels:
provider: gcp
writeConnectionSecretToRef:
name: db-conn
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-gcp.yaml
```
</div>
<div class="tab-pane fade" id="azure-tab-2" markdown="1">
```yaml
apiVersion: database.example.org/v1alpha1
kind: PostgreSQLInstance
metadata:
name: my-db
namespace: default
spec:
parameters:
storageGB: 20
compositionSelector:
matchLabels:
provider: azure
writeConnectionSecretToRef:
name: db-conn
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-azure.yaml
```
</div>
<div class="tab-pane fade" id="alibaba-tab-2" markdown="1">
```yaml
apiVersion: database.example.org/v1alpha1
kind: PostgreSQLInstance
metadata:
name: my-db
namespace: default
spec:
parameters:
storageGB: 20
compositionSelector:
matchLabels:
provider: alibaba
writeConnectionSecretToRef:
name: db-conn
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-alibaba.yaml
```
</div>
</div>
After creating the `PostgreSQLInstance` Crossplane will begin provisioning a
database instance on your provider of choice. Once provisioning is complete, you
should see `READY: True` in the output when you run:
```console
kubectl get postgresqlinstance my-db
```
> Note: while waiting for the `PostgreSQLInstance` to become ready, you
> may want to look at other resources in your cluster. The following commands
> will allow you to view groups of Crossplane resources:
>
> - `kubectl get claim`: get all resources of all claim kinds, like `PostgreSQLInstance`.
> - `kubectl get composite`: get all resources that are of composite kind, like `CompositePostgreSQLInstance`.
> - `kubectl get managed`: get all resources that represent a unit of external
> infrastructure.
> - `kubectl get <name-of-provider>`: get all resources related to `<provider>`.
> - `kubectl get crossplane`: get all resources related to Crossplane.
Try the following command to watch your provisioned resources become ready:
```console
kubectl get crossplane -l crossplane.io/claim-name=my-db
```
Once your `PostgreSQLInstance` is ready, you should see a `Secret` in the `default`
namespace named `db-conn` that contains keys that we defined in XRD. If they were
filled by the composition, then they should appear:
```console
$ kubectl describe secrets db-conn
Name: db-conn
Namespace: default
...
Type: connection.crossplane.io/v1alpha1
Data
====
password: 27 bytes
port: 4 bytes
username: 25 bytes
endpoint: 45 bytes
```
## Consume Your Infrastructure
Because connection secrets are written as a Kubernetes `Secret` they can easily
be consumed by Kubernetes primitives. The most basic building block in
Kubernetes is the `Pod`. Let's define a `Pod` that will show that we are able to
connect to our newly provisioned database.
> Note that if you're using a hosted Crossplane you'll need to copy the db-conn
> connection secret over to your own Kubernetes cluster and run this pod there.
```yaml
apiVersion: v1
kind: Pod
metadata:
name: see-db
namespace: default
spec:
containers:
- name: see-db
image: postgres:9.6
command: ['psql']
args: ['-c', 'SELECT current_database();']
env:
- name: PGDATABASE
value: postgres
- name: PGHOST
valueFrom:
secretKeyRef:
name: db-conn
key: endpoint
- name: PGUSER
valueFrom:
secretKeyRef:
name: db-conn
key: username
- name: PGPASSWORD
valueFrom:
secretKeyRef:
name: db-conn
key: password
- name: PGPORT
valueFrom:
secretKeyRef:
name: db-conn
key: port
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/pod.yaml
```
This `Pod` simply connects to a PostgreSQL database and prints its name, so you
should see the following output (or similar) after creating it if you run
`kubectl logs see-db`:
```SQL
current_database
------------------
postgres
(1 row)
```
## Clean Up
To clean up the `Pod`, run:
```console
kubectl delete pod see-db
```
To clean up the infrastructure that was provisioned, you can delete the
`PostgreSQLInstance` XRC:
```console
kubectl delete postgresqlinstance my-db
```
> Don't clean up your `Configuration` just yet if you plan to continue on to the
> next section of the guide! We'll use them again when we deploy an OAM
> application.
## Next Steps
Now you have seen how to provision and publish more complex infrastructure
setups. In the [next section] you will learn how to consume infrastructure
alongside your [OAM] application manifests.
<!-- Named Links -->
[last section]: provision-infrastructure.md
[composition]: ../concepts/composition.md
[package]: ../concepts/packages.md
[setup]: install-configure.md
[next section]: run-applications.md
[OAM]: https://oam.dev/

133
docs/master/getting-started/package-infrastructure.md → docs/master/getting-started/create-configuration.md
View File

@ -1,35 +1,24 @@
--- ---
title: Package Infrastructure title: Create a Configuration
toc: true toc: true
weight: 6 weight: 4
indent: true indent: true
--- ---
# Package Infrastructure # Create a Configuration
In a [previous section] we learned that Crossplane can be configured with new In the [previous section] we were able to create a PostgreSQL database because
composite resources (XRs) that are [composed] of other resources, allowing you we had installed a configuration package that defined the `PostgreSQLInstance`
to define and offer resources that group and abstract infrastructure primitives. type and a `Composition` of managed resources that mapped to it. Crossplane
We use two special Crossplane resources to define and configure new XRs and allows you to define your own composite resources (XRs) and compositions, then
XRCs: package them up to be easily distributed as OCI images. This allows you to
construct a reproducible platform that exposes infrastructure APIs at your
- A `CompositeResourceDefinition` (XRD) _defines_ a new kind of composite desired level of abstraction, and can be installed into any Crossplane cluster.
resource, including its schema. An XRD may optionally _offer_ a claim.
- A `Composition` specifies which resources a composite resource will be
composed of, and how they should be configured. You can create multiple
`Composition` options for each composite resource.
XRDs and Compositions may be [packaged] as a _configuration_, that may easily be
installed to Crossplane by creating a declarative `Configuration` resource, or
by using `kubectl crossplane install configuration`. In the examples below we
will build and push a configuration that defines a new
`CompositePostgreSQLInstance` XR that takes a single `storageGB` parameter, and
creates a connection `Secret` with keys for `username`, `password`, and
`endpoint`.
## Create a Configuration Directory ## Create a Configuration Directory
Our configuration will consist of three files: We are going to build the same configuration package that we previously
installed. It will consist of three files:
* `crossplane.yaml` - Metadata about the configuration. * `crossplane.yaml` - Metadata about the configuration.
* `definition.yaml` - The XRD. * `definition.yaml` - The XRD.
@ -53,6 +42,10 @@ cd crossplane-config
We'll create the aforementioned three files in this directory, then build them We'll create the aforementioned three files in this directory, then build them
into a package. into a package.
> Note that `definition.yaml` and `composition.yaml` could be created directly
> in the Crossplane cluster without packaging them into a configuration. This
> can be useful for testing compositions before pushing them to a registry.
## Create CompositeResourceDefinition ## Create CompositeResourceDefinition
First we'll create a `CompositeResourceDefinition` (XRD) to define the schema of First we'll create a `CompositeResourceDefinition` (XRD) to define the schema of
@ -119,7 +112,6 @@ instance on the chosen provider.
<li><a href="#aws-new-tab-2" data-toggle="tab">AWS (New VPC)</a></li> <li><a href="#aws-new-tab-2" data-toggle="tab">AWS (New VPC)</a></li>
<li><a href="#gcp-tab-2" data-toggle="tab">GCP</a></li> <li><a href="#gcp-tab-2" data-toggle="tab">GCP</a></li>
<li><a href="#azure-tab-2" data-toggle="tab">Azure</a></li> <li><a href="#azure-tab-2" data-toggle="tab">Azure</a></li>
<li><a href="#alibaba-tab-2" data-toggle="tab">Alibaba</a></li>
</ul> </ul>
<br> <br>
<div class="tab-content"> <div class="tab-content">
@ -563,7 +555,6 @@ so that Crossplane users may install it.
<li><a href="#aws-new-tab-3" data-toggle="tab">AWS (New VPC)</a></li> <li><a href="#aws-new-tab-3" data-toggle="tab">AWS (New VPC)</a></li>
<li><a href="#gcp-tab-3" data-toggle="tab">GCP</a></li> <li><a href="#gcp-tab-3" data-toggle="tab">GCP</a></li>
<li><a href="#azure-tab-3" data-toggle="tab">Azure</a></li> <li><a href="#azure-tab-3" data-toggle="tab">Azure</a></li>
<li><a href="#alibaba-tab-3" data-toggle="tab">Alibaba</a></li>
</ul> </ul>
<br> <br>
<div class="tab-content"> <div class="tab-content">
@ -578,15 +569,28 @@ metadata:
guide: quickstart guide: quickstart
provider: aws provider: aws
vpc: default vpc: default
spec:
crossplane:
version: ">=v1.0.0-0"
dependsOn:
- provider: crossplane/provider-aws
version: ">=v0.14.0"
``` ```
```console ```console
curl -OL https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/package/aws/crossplane.yaml curl -OL https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/package/aws/crossplane.yaml
kubectl crossplane build configuration
```
You should see a file in your working directory with a `.xpkg` extension. The
Crossplane CLI will automatically tag and push it to the registry of your
choosing in the next step if it is the only `.xpkg` in the directory. Otherwise
you may specify a specific package by using the `-f` flag.
```console
# Set this to the Docker Hub username or OCI registry you wish to use. # Set this to the Docker Hub username or OCI registry you wish to use.
REG=my-package-repo REG=my-package-repo
kubectl crossplane build configuration
kubectl crossplane push configuration ${REG}/getting-started-with-aws:master kubectl crossplane push configuration ${REG}/getting-started-with-aws:master
``` ```
@ -605,15 +609,28 @@ metadata:
guide: quickstart guide: quickstart
provider: aws provider: aws
vpc: new vpc: new
spec:
crossplane:
version: ">=v1.0.0-0"
dependsOn:
- provider: crossplane/provider-aws
version: ">=v0.14.0"
``` ```
```console ```console
curl -OL https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/package/aws-with-vpc/crossplane.yaml curl -OL https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/package/aws-with-vpc/crossplane.yaml
kubectl crossplane build configuration
```
You should see a file in your working directory with a `.xpkg` extension. The
Crossplane CLI will automatically tag and push it to the registry of your
choosing in the next step if it is the only `.xpkg` in the directory. Otherwise
you may specify a specific package by using the `-f` flag.
```console
# Set this to the Docker Hub username or OCI registry you wish to use. # Set this to the Docker Hub username or OCI registry you wish to use.
REG=my-package-repo REG=my-package-repo
kubectl crossplane build configuration
kubectl crossplane push configuration ${REG}/getting-started-with-aws-with-vpc:master kubectl crossplane push configuration ${REG}/getting-started-with-aws-with-vpc:master
``` ```
@ -631,15 +648,28 @@ metadata:
annotations: annotations:
guide: quickstart guide: quickstart
provider: gcp provider: gcp
spec:
crossplane:
version: ">=v1.0.0-0"
dependsOn:
- provider: crossplane/provider-gcp
version: ">=v0.13.0"
``` ```
```console ```console
curl -OL https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/package/gcp/crossplane.yaml curl -OL https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/package/gcp/crossplane.yaml
kubectl crossplane build configuration
```
You should see a file in your working directory with a `.xpkg` extension. The
Crossplane CLI will automatically tag and push it to the registry of your
choosing in the next step if it is the only `.xpkg` in the directory. Otherwise
you may specify a specific package by using the `-f` flag.
```console
# Set this to the Docker Hub username or OCI registry you wish to use. # Set this to the Docker Hub username or OCI registry you wish to use.
REG=my-package-repo REG=my-package-repo
kubectl crossplane build configuration
kubectl crossplane push configuration ${REG}/getting-started-with-gcp:master kubectl crossplane push configuration ${REG}/getting-started-with-gcp:master
``` ```
@ -657,42 +687,29 @@ metadata:
annotations: annotations:
guide: quickstart guide: quickstart
provider: azure provider: azure
spec:
crossplane:
version: ">=v1.0.0-0"
dependsOn:
- provider: crossplane/provider-azure
version: ">=v0.13.0"
``` ```
```console ```console
curl -OL https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/package/azure/crossplane.yaml curl -OL https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/package/azure/crossplane.yaml
# Set this to the Docker Hub username or OCI registry you wish to use.
REG=my-package-repo
kubectl crossplane build configuration kubectl crossplane build configuration
kubectl crossplane push configuration ${REG}/getting-started-with-azure:master
``` ```
> Note that the Crossplane CLI will not follow symbolic links for files in the You should see a file in your working directory with a `.xpkg` extension. The
> root package directory. Crossplane CLI will automatically tag and push it to the registry of your
choosing in the next step if it is the only `.xpkg` in the directory. Otherwise
</div> you may specify a specific package by using the `-f` flag.
<div class="tab-pane fade" id="alibaba-tab-3" markdown="1">
```yaml
apiVersion: meta.pkg.crossplane.io/v1
kind: Configuration
metadata:
name: getting-started-with-alibaba
annotations:
guide: quickstart
provider: alibaba
```
```console ```console
curl -OL https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/package/alibaba/crossplane.yaml
# Set this to the Docker Hub username or OCI registry you wish to use. # Set this to the Docker Hub username or OCI registry you wish to use.
REG=my-package-repo REG=my-package-repo
kubectl crossplane push configuration ${REG}/getting-started-with-azure:master
kubectl crossplane build configuration
kubectl crossplane push configuration ${REG}/getting-started-with-alibaba:master
``` ```
> Note that the Crossplane CLI will not follow symbolic links for files in the > Note that the Crossplane CLI will not follow symbolic links for files in the
@ -703,7 +720,7 @@ kubectl crossplane push configuration ${REG}/getting-started-with-alibaba:master
That's it! You've now built and pushed your package. Take a look at the That's it! You've now built and pushed your package. Take a look at the
Crossplane [packages] documentation for more information about installing and Crossplane [packages] documentation for more information about installing and
working with packages. working with packages, or read about other Crossplane [concepts].
## Clean Up ## Clean Up
@ -716,9 +733,9 @@ rm -rf crossplane-config
<!-- Named Links --> <!-- Named Links -->
[previous section]: compose-infrastructure.md [previous section]: provision-infrastructure.md
[composed]: ../concepts/composition.md [composed]: ../concepts/composition.md
[composition]: ../concepts/composition.md [composition]: ../concepts/composition.md
[Docker Hub]: https://hub.docker.com/ [Docker Hub]: https://hub.docker.com/
[packages]: ../concepts/packages.md [packages]: ../concepts/packages.md
[packaged]: ../concepts/packages.md [concepts]: ../concepts/overview.md

240
docs/master/getting-started/install-configure.md
View File

@ -201,29 +201,58 @@ curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.
</div> </div>
</div> </div>
## Select Provider ## Select a Getting Started Configuration
Crossplane goes beyond simply modelling infrastructure primitives as custom
resources - it enables you to define new custom resources with schemas of your
choosing. We call these "composite resources" (XRs). Composite resources compose
managed resources -- Kubernetes custom resources that offer a high fidelity
representation of an infrastructure primitive, like an SQL instance or a
firewall rule.
We use two special Crossplane resources to define and configure these new custom
resources:
- A `CompositeResourceDefinition` (XRD) _defines_ a new kind of composite
resource, including its schema. An XRD may optionally _offer_ a claim (XRC).
- A `Composition` specifies which resources a composite resource will be
composed of, and how they should be configured. You can create multiple
`Composition` options for each composite resource.
XRDs and Compositions may be packaged and installed as a _configuration_. A
configuration is a [package] of composition configuration that can easily be
installed to Crossplane by creating a declarative `Configuration` resource, or
by using `kubectl crossplane install configuration`.
In the examples below we will install a configuration that defines a new
`CompositePostgreSQLInstance` XR and `PostgreSQLInstance` XRC that takes a
single `storageGB` parameter, and creates a connection `Secret` with keys for
`username`, `password`, and `endpoint`. A `Configuration` exists for each
provider that can satisfy a `PostgreSQLInstance`. Let's get started!
Now from your terminal, install and configure a provider for Crossplane to use
for infrastructure provisioning:
<ul class="nav nav-tabs"> <ul class="nav nav-tabs">
<li class="active"><a href="#provider-tab-aws" data-toggle="tab">AWS</a></li> <li class="active"><a href="#aws-tab-1" data-toggle="tab">AWS (Default VPC)</a></li>
<li><a href="#provider-tab-gcp" data-toggle="tab">GCP</a></li> <li><a href="#aws-new-tab-1" data-toggle="tab">AWS (New VPC)</a></li>
<li><a href="#provider-tab-azure" data-toggle="tab">Azure</a></li> <li><a href="#gcp-tab-1" data-toggle="tab">GCP</a></li>
<li><a href="#provider-tab-alibaba" data-toggle="tab">Alibaba</a></li> <li><a href="#azure-tab-1" data-toggle="tab">Azure</a></li>
</ul> </ul>
<br> <br>
<div class="tab-content"> <div class="tab-content">
<div class="tab-pane fade in active" id="provider-tab-aws" markdown="1"> <div class="tab-pane fade in active" id="aws-tab-1" markdown="1">
### Install AWS Provider ### Install Configuration Package
> If you prefer to see the contents of this configuration package and how it is
> constructed prior to install, skip ahead to the [create a configuration]
> section.
```console ```console
kubectl crossplane install provider crossplane/provider-aws:v0.16.0 kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-aws:latest
``` ```
Wait until the provider becomes healthy: Wait until all packages become healthy:
``` ```
kubectl get provider.pkg --watch kubectl get pkg --watch
``` ```
### Get AWS Account Keyfile ### Get AWS Account Keyfile
@ -237,7 +266,7 @@ AWS_PROFILE=default && echo -e "[default]\naws_access_key_id = $(aws configure g
### Create a Provider Secret ### Create a Provider Secret
```console ```console
kubectl create secret generic aws-creds -n crossplane-system --from-file=key=./creds.conf kubectl create secret generic aws-creds -n crossplane-system --from-file=creds=./creds.conf
``` ```
### Configure the Provider ### Configure the Provider
@ -256,24 +285,82 @@ spec:
secretRef: secretRef:
namespace: crossplane-system namespace: crossplane-system
name: aws-creds name: aws-creds
key: key key: creds
``` ```
```console ```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/aws/providerconfig.yaml kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/aws/providerconfig.yaml
``` ```
</div> </div>
<div class="tab-pane fade" id="provider-tab-gcp" markdown="1"> <div class="tab-pane fade" id="aws-new-tab-1" markdown="1">
### Install GCP Provider ### Install Configuration Package
> If you prefer to see the contents of this configuration package and how it is
> constructed prior to install, skip ahead to the [create a configuration]
> section.
```console ```console
kubectl crossplane install provider crossplane/provider-gcp:v0.14.0 kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-aws-with-vpc:latest
``` ```
Wait until the provider becomes healthy: Wait until all packages become healthy:
``` ```
kubectl get provider.pkg --watch kubectl get pkg --watch
```
### Get AWS Account Keyfile
Using an AWS account with permissions to manage RDS databases:
```console
AWS_PROFILE=default && echo -e "[default]\naws_access_key_id = $(aws configure get aws_access_key_id --profile $AWS_PROFILE)\naws_secret_access_key = $(aws configure get aws_secret_access_key --profile $AWS_PROFILE)" > creds.conf
```
### Create a Provider Secret
```console
kubectl create secret generic aws-creds -n crossplane-system --from-file=creds=./creds.conf
```
### Configure the Provider
We will create the following `ProviderConfig` object to configure credentials
for AWS Provider:
```yaml
apiVersion: aws.crossplane.io/v1beta1
kind: ProviderConfig
metadata:
name: default
spec:
credentials:
source: Secret
secretRef:
namespace: crossplane-system
name: aws-creds
key: creds
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/aws/providerconfig.yaml
```
</div>
<div class="tab-pane fade" id="gcp-tab-1" markdown="1">
### Install Configuration Package
> If you prefer to see the contents of this configuration package and how it is
> constructed prior to install, skip ahead to the [create a configuration]
> section.
```console
kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-gcp:latest
```
Wait until all packages become healthy:
```
kubectl get pkg --watch
``` ```
### Get GCP Account Keyfile ### Get GCP Account Keyfile
@ -303,7 +390,7 @@ gcloud iam service-accounts keys create creds.json --project $PROJECT_ID --iam-a
### Create a Provider Secret ### Create a Provider Secret
```console ```console
kubectl create secret generic gcp-creds -n crossplane-system --from-file=key=./creds.json kubectl create secret generic gcp-creds -n crossplane-system --from-file=creds=./creds.json
``` ```
### Configure the Provider ### Configure the Provider
@ -325,21 +412,25 @@ spec:
secretRef: secretRef:
namespace: crossplane-system namespace: crossplane-system
name: gcp-creds name: gcp-creds
key: key" | kubectl apply -f - key: creds" | kubectl apply -f -
``` ```
</div> </div>
<div class="tab-pane fade" id="provider-tab-azure" markdown="1"> <div class="tab-pane fade" id="azure-tab-1" markdown="1">
### Install Azure Provider ### Install Configuration Package
> If you prefer to see the contents of this configuration package and how it is
> constructed prior to install, skip ahead to the [create a configuration]
> section.
```console ```console
kubectl crossplane install provider crossplane/provider-azure:v0.14.0 kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-azure:latest
``` ```
Wait until the provider becomes healthy: Wait until all packages become healthy:
``` ```
kubectl get provider.pkg --watch kubectl get pkg --watch
``` ```
### Get Azure Principal Keyfile ### Get Azure Principal Keyfile
@ -368,7 +459,7 @@ az ad app permission admin-consent --id "${AZURE_CLIENT_ID}"
### Create a Provider Secret ### Create a Provider Secret
```console ```console
kubectl create secret generic azure-creds -n crossplane-system --from-file=key=./creds.json kubectl create secret generic azure-creds -n crossplane-system --from-file=creds=./creds.json
``` ```
### Configure the Provider ### Configure the Provider
@ -387,116 +478,35 @@ spec:
secretRef: secretRef:
namespace: crossplane-system namespace: crossplane-system
name: azure-creds name: azure-creds
key: key key: creds
``` ```
```console ```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/azure/providerconfig.yaml kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/azure/providerconfig.yaml
``` ```
</div>
<div class="tab-pane fade" id="provider-tab-alibaba" markdown="1">
### Install Alibaba Provider
```console
kubectl crossplane install provider crossplane/provider-alibaba:v0.5.0
```
Wait until the provider becomes healthy:
```
kubectl get provider.pkg --watch
```
### Create a Provider Secret
```console
# Replace <your-key> and <your-secret> with your actual key id and key secret.
kubectl create secret generic alibaba-creds --from-literal=accessKeyId=<your-key> --from-literal=accessKeySecret=<your-secret> -n crossplane-system
```
### Configure the Provider
We will create the following `ProviderConfig` object to configure credentials
for Alibaba Provider:
```yaml
apiVersion: alibaba.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
name: default
spec:
region: cn-beijing
credentials:
source: Secret
secretRef:
namespace: crossplane-system
name: alibaba-creds
# "key" field does not have any effect right now but it has to be given.
# See https://github.com/crossplane/crossplane-runtime/issues/215
key: credentials
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/alibaba/providerconfig.yaml
```
</div> </div>
</div> </div>
## Next Steps ## Next Steps
Now that you have a provider configured, you can [provision infrastructure]. Now that you have configured Crossplane with support for `PostgreSQLInstance`,
you can [provision infrastructure].
## More Info ## More Info
See [Install] and [Configure] docs for installing alternate versions and more See [Install] and [Configure] docs for installing alternate versions and more
detailed instructions. detailed instructions.
## Uninstall Provider See [Uninstall] docs for cleaning up resources, packages, and Crossplane itself.
Let's check whether there are any managed resources before deleting the
provider.
```console
kubectl get managed
```
If there are any, please delete them first, so you don't lose the track of them.
Then delete all the `ProviderConfig`s you created. An example command if you used
AWS Provider:
```
kubectl delete providerconfig.aws --all
```
List installed providers:
```console
kubectl get provider.pkg
```
Delete the one you want to delete:
```
kubectl delete provider.pkg <provider-name>
```
## Uninstall Crossplane
```console
helm delete crossplane --namespace crossplane-system
kubectl delete namespace crossplane-system
```
Helm does not delete CRD objects. You can delete the ones Crossplane created with
the following commands:
```
kubectl patch lock lock -p '{"metadata":{"finalizers": []}}' --type=merge
kubectl get crd -o name | grep crossplane.io | xargs kubectl delete
```
<!-- Named Links --> <!-- Named Links -->
[package]: ../concepts/packages.md
[provision infrastructure]: provision-infrastructure.md [provision infrastructure]: provision-infrastructure.md
[create a configuration]: create-configuration.md
[Install]: ../reference/install.md [Install]: ../reference/install.md
[Configure]: ../reference/configure.md [Configure]: ../reference/configure.md
[Uninstall]: ../reference/uninstall.md
[Kubernetes cluster]: https://kubernetes.io/docs/setup/ [Kubernetes cluster]: https://kubernetes.io/docs/setup/
[Minikube]: https://kubernetes.io/docs/tasks/tools/install-minikube/ [Minikube]: https://kubernetes.io/docs/tasks/tools/install-minikube/
[Helm]:https://docs.helm.sh/using_helm/ [Helm]:https://docs.helm.sh/using_helm/

405
docs/master/getting-started/provision-infrastructure.md
View File

@ -7,252 +7,277 @@ indent: true
# Provision Infrastructure # Provision Infrastructure
Crossplane allows you to provision infrastructure anywhere using the Kubernetes Composite resources (XRs) are always cluster scoped - they exist outside of any
API. Once you have [installed a provider] and [configured your credentials], you namespace. This allows an XR to represent infrastructure that might be consumed
can create any infrastructure currently supported by the provider. Let's start from several different namespaces. This is often true for VPC networks - an
by provisioning a database on your provider of choice. infrastructure operator may wish to define a VPC network XR and an SQL instance
XR, only the latter of which may be managed by application operators. The
application operators are restricted to their team's namespace, but their SQL
instances should all be attached to the VPC network that the infrastructure
operator manages. Crossplane enables scenarios like this by allowing the
infrastructure operator to offer their application operators a _composite
resource claim_ (XRC). An XRC is a namespaced proxy for an XR; the schema of an
XRC is identical to that of its corresponding XR. When an application operator
creates an XRC, a corresponding backing XR is created automatically. This model
has similarities to [Persistent Volumes (PV) and Persistent Volume Claims (PVC)]
in Kubernetes.
Each provider below offers their own flavor of a managed database. When you ## Claim Your Infrastructure
install a provider it extends Crossplane by adding support for several "managed
resources". A managed resource is a cluster-scoped Kubernetes custom resource The `Configuration` package we installed in the last section:
that represents an infrastructure object, such as a database instance.
- Defines a `CompositePostgreSQLInstance` XR.
- Offers a `PostgreSQLInstance` claim (XRC) for said XR.
- Creates a `Composition` that can satisfy our XR.
This means that we can create a `PostgreSQLInstance` XRC in the `default`
namespace to provision a PostgreSQL instance and all the supporting
infrastructure (VPCs, firewall rules, resource groups, etc) that it may need!
<ul class="nav nav-tabs"> <ul class="nav nav-tabs">
<li class="active"><a href="#aws-tab-1" data-toggle="tab">AWS</a></li> <li class="active"><a href="#aws-tab-2" data-toggle="tab">AWS (Default VPC)</a></li>
<li><a href="#gcp-tab-1" data-toggle="tab">GCP</a></li> <li><a href="#aws-new-tab-2" data-toggle="tab">AWS (New VPC)</a></li>
<li><a href="#azure-tab-1" data-toggle="tab">Azure</a></li> <li><a href="#gcp-tab-2" data-toggle="tab">GCP</a></li>
<li><a href="#alibaba-tab-1" data-toggle="tab">Alibaba</a></li> <li><a href="#azure-tab-2" data-toggle="tab">Azure</a></li>
</ul> </ul>
<br> <br>
<div class="tab-content"> <div class="tab-content">
<div class="tab-pane fade in active" id="aws-tab-1" markdown="1"> <div class="tab-pane fade in active" id="aws-tab-2" markdown="1">
The AWS provider supports provisioning an [RDS] instance via the `RDSInstance` > Note that this resource will create an RDS instance using your default VPC,
managed resource it adds to Crossplane. > which may or may not allow connections from the internet depending on how it
> is configured.
```yaml ```yaml
apiVersion: database.aws.crossplane.io/v1beta1 apiVersion: database.example.org/v1alpha1
kind: RDSInstance kind: PostgreSQLInstance
metadata: metadata:
name: rdspostgresql name: my-db
namespace: default
spec: spec:
forProvider: parameters:
region: us-east-1 storageGB: 20
dbInstanceClass: db.t2.small compositionSelector:
masterUsername: masteruser matchLabels:
allocatedStorage: 20 provider: aws
engine: postgres vpc: default
engineVersion: "9.6"
skipFinalSnapshotBeforeDeletion: true
writeConnectionSecretToRef: writeConnectionSecretToRef:
namespace: crossplane-system name: db-conn
name: aws-rdspostgresql-conn
``` ```
```console ```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/provision/aws.yaml kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-aws.yaml
```
Creating the above instance will cause Crossplane to provision an RDS instance
on AWS. You can view the progress with the following command:
```console
kubectl get rdsinstance rdspostgresql
```
When provisioning is complete, you should see `READY: True` in the output. You
can take a look at its connection secret that is referenced under `spec.writeConnectionSecretToRef`:
```console
kubectl describe secret aws-rdspostgresql-conn -n crossplane-system
```
You can then delete the `RDSInstance`:
```console
kubectl delete rdsinstance rdspostgresql
``` ```
</div> </div>
<div class="tab-pane fade" id="gcp-tab-1" markdown="1"> <div class="tab-pane fade" id="aws-new-tab-2" markdown="1">
The GCP provider supports provisioning a [CloudSQL] instance with the > Note that this resource also includes several networking managed resources
`CloudSQLInstance` managed resource it adds to Crossplane. > that are required to provision a publicly available PostgreSQL instance.
> Composition enables scenarios such as this, as well as far more complex ones.
> See the [composition] documentation for more information.
```yaml ```yaml
apiVersion: database.gcp.crossplane.io/v1beta1 apiVersion: database.example.org/v1alpha1
kind: CloudSQLInstance kind: PostgreSQLInstance
metadata: metadata:
name: cloudsqlpostgresql name: my-db
namespace: default
spec: spec:
forProvider: parameters:
databaseVersion: POSTGRES_9_6 storageGB: 20
region: us-central1 compositionSelector:
settings: matchLabels:
tier: db-custom-1-3840 provider: aws
dataDiskType: PD_SSD vpc: new
dataDiskSizeGb: 10
writeConnectionSecretToRef: writeConnectionSecretToRef:
namespace: crossplane-system name: db-conn
name: cloudsqlpostgresql-conn
``` ```
```console ```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/provision/gcp.yaml kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-aws.yaml
```
Creating the above instance will cause Crossplane to provision a CloudSQL
instance on GCP. You can view the progress with the following command:
```console
kubectl get cloudsqlinstance cloudsqlpostgresql
```
When provisioning is complete, you should see `READY: True` in the output. You
can take a look at its connection secret that is referenced under `spec.writeConnectionSecretToRef`:
```console
kubectl describe secret cloudsqlpostgresql-conn -n crossplane-system
```
You can then delete the `CloudSQLInstance`:
```console
kubectl delete cloudsqlinstance cloudsqlpostgresql
``` ```
</div> </div>
<div class="tab-pane fade" id="azure-tab-1" markdown="1"> <div class="tab-pane fade" id="gcp-tab-2" markdown="1">
The Azure provider supports provisioning an [Azure Database for PostgreSQL]
instance with the `PostgreSQLServer` managed resource it adds to Crossplane.
> Note: provisioning an Azure Database for PostgreSQL requires the presence of a
> [Resource Group] in your Azure account. We go ahead and provision a new
> `ResourceGroup` here in case you do not already have a suitable one in your
> account.
```yaml ```yaml
apiVersion: azure.crossplane.io/v1alpha3 apiVersion: database.example.org/v1alpha1
kind: ResourceGroup kind: PostgreSQLInstance
metadata: metadata:
name: sqlserverpostgresql-rg name: my-db
namespace: default
spec: spec:
location: West US 2 parameters:
--- storageGB: 20
apiVersion: database.azure.crossplane.io/v1beta1 compositionSelector:
kind: PostgreSQLServer matchLabels:
metadata: provider: gcp
name: sqlserverpostgresql
spec:
forProvider:
administratorLogin: myadmin
resourceGroupNameRef:
name: sqlserverpostgresql-rg
location: West US 2
sslEnforcement: Disabled
version: "9.6"
sku:
tier: GeneralPurpose
capacity: 2
family: Gen5
storageProfile:
storageMB: 20480
writeConnectionSecretToRef: writeConnectionSecretToRef:
namespace: crossplane-system name: db-conn
name: sqlserverpostgresql-conn
``` ```
```console ```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/provision/azure.yaml kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-gcp.yaml
```
Creating the above instance will cause Crossplane to provision a PostgreSQL
database instance on Azure. You can view the progress with the following
command:
```console
kubectl get postgresqlserver sqlserverpostgresql
```
When provisioning is complete, you should see `READY: True` in the output. You
can take a look at its connection secret that is referenced under `spec.writeConnectionSecretToRef`:
```console
kubectl describe secret sqlserverpostgresql-conn -n crossplane-system
```
You can then delete the `PostgreSQLServer`:
```console
kubectl delete postgresqlserver sqlserverpostgresql
kubectl delete resourcegroup sqlserverpostgresql-rg
``` ```
</div> </div>
<div class="tab-pane fade" id="alibaba-tab-1" markdown="1"> <div class="tab-pane fade" id="azure-tab-2" markdown="1">
The Alibaba provider supports provisioning an [ApsaraDB for RDS] instance with
the `RDSInstance` managed resource it adds to Crossplane.
```yaml ```yaml
apiVersion: database.alibaba.crossplane.io/v1alpha1 apiVersion: database.example.org/v1alpha1
kind: RDSInstance kind: PostgreSQLInstance
metadata: metadata:
name: rdspostgresql name: my-db
namespace: default
spec: spec:
forProvider: parameters:
engine: PostgreSQL storageGB: 20
engineVersion: "9.4" compositionSelector:
dbInstanceClass: rds.pg.s1.small matchLabels:
dbInstanceStorageInGB: 20 provider: azure
securityIPList: "0.0.0.0/0"
masterUsername: "test123"
writeConnectionSecretToRef: writeConnectionSecretToRef:
namespace: crossplane-system name: db-conn
name: alibaba-rdspostgresql-conn
``` ```
```console ```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/provision/alibaba.yaml kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-azure.yaml
```
Creating the above instance will cause Crossplane to provision an RDS instance
on Alibaba. You can view the progress with the following command:
```console
kubectl get rdsinstance rdspostgresql
```
When provisioning is complete, you should see `READY: True` in the output. You
can take a look at its connection secret that is referenced under `spec.writeConnectionSecretToRef`:
```console
kubectl describe secret alibaba-rdspostgresql-conn -n crossplane-system
```
You can then delete the `RDSInstance`:
```console
kubectl delete rdsinstance rdspostgresql
``` ```
</div> </div>
</div> </div>
After creating the `PostgreSQLInstance` Crossplane will begin provisioning a
database instance on your provider of choice. Once provisioning is complete, you
should see `READY: True` in the output when you run:
```console
kubectl get postgresqlinstance my-db
```
> Note: while waiting for the `PostgreSQLInstance` to become ready, you
> may want to look at other resources in your cluster. The following commands
> will allow you to view groups of Crossplane resources:
>
> - `kubectl get claim`: get all resources of all claim kinds, like `PostgreSQLInstance`.
> - `kubectl get composite`: get all resources that are of composite kind, like `CompositePostgreSQLInstance`.
> - `kubectl get managed`: get all resources that represent a unit of external
> infrastructure.
> - `kubectl get <name-of-provider>`: get all resources related to `<provider>`.
> - `kubectl get crossplane`: get all resources related to Crossplane.
Try the following command to watch your provisioned resources become ready:
```console
kubectl get crossplane -l crossplane.io/claim-name=my-db
```
Once your `PostgreSQLInstance` is ready, you should see a `Secret` in the `default`
namespace named `db-conn` that contains keys that we defined in XRD. If they were
filled by the composition, then they should appear:
```console
$ kubectl describe secrets db-conn
Name: db-conn
Namespace: default
...
Type: connection.crossplane.io/v1alpha1
Data
====
password: 27 bytes
port: 4 bytes
username: 25 bytes
endpoint: 45 bytes
```
## Consume Your Infrastructure
Because connection secrets are written as a Kubernetes `Secret` they can easily
be consumed by Kubernetes primitives. The most basic building block in
Kubernetes is the `Pod`. Let's define a `Pod` that will show that we are able to
connect to our newly provisioned database.
> Note that if you're using a hosted Crossplane you'll need to copy the db-conn
> connection secret over to your own Kubernetes cluster and run this pod there.
```yaml
apiVersion: v1
kind: Pod
metadata:
name: see-db
namespace: default
spec:
containers:
- name: see-db
image: postgres:9.6
command: ['psql']
args: ['-c', 'SELECT current_database();']
env:
- name: PGDATABASE
value: postgres
- name: PGHOST
valueFrom:
secretKeyRef:
name: db-conn
key: endpoint
- name: PGUSER
valueFrom:
secretKeyRef:
name: db-conn
key: username
- name: PGPASSWORD
valueFrom:
secretKeyRef:
name: db-conn
key: password
- name: PGPORT
valueFrom:
secretKeyRef:
name: db-conn
key: port
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/pod.yaml
```
This `Pod` simply connects to a PostgreSQL database and prints its name, so you
should see the following output (or similar) after creating it if you run
`kubectl logs see-db`:
```SQL
current_database
------------------
postgres
(1 row)
```
## Clean Up
To clean up the `Pod`, run:
```console
kubectl delete pod see-db
```
To clean up the infrastructure that was provisioned, you can delete the
`PostgreSQLInstance` XRC:
```console
kubectl delete postgresqlinstance my-db
```
## Next Steps ## Next Steps
Now that you have seen how to provision individual managed resources, let's take Now you have seen how to provision and consume complex infrastructure via
a look at how we can compose several managed resources into new resources with composition. In the [next section] you will learn how compose and package your
APIs of our choosing in the [next section]. own infrastructure APIs.
<!-- Named Links --> <!-- Named Links -->
[installed a provider]: install-configure.md [Persistent Volumes (PV) and Persistent Volume Claims (PVC)]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/
[configured your credentials]: install-configure.md [composition]: ../concepts/composition.md
[RDS]: https://aws.amazon.com/rds/ [setup]: install-configure.md
[CloudSQL]: https://cloud.google.com/sql [next section]: create-configuration.md
[Azure Database for PostgreSQL]: https://azure.microsoft.com/en-us/services/postgresql/
[Resource Group]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal#what-is-a-resource-group
[ApsaraDB for RDS]: https://www.alibabacloud.com/product/apsaradb-for-rds-postgresql
[next section]: compose-infrastructure.md

236
docs/master/guides/direct-managed.md Normal file
View File

@ -0,0 +1,236 @@
---
title: Managed Resources
toc: true
weight: 250
indent: true
---
# Using Managed Resources Directly
Crossplane allows you to provision infrastructure anywhere using the Kubernetes
API. While users are encouraged to make use of [composition] to expose
infrastructure resources, you may opt to use managed resources directly. Once
you have [installed a provider] and [configured your credentials], you can
create any infrastructure currently supported by the provider. Let's start by
provisioning a database on your provider of choice.
Each provider below offers their own flavor of a managed database. When you
install a provider it extends Crossplane by adding support for several "managed
resources". A managed resource is a cluster-scoped Kubernetes custom resource
that represents an infrastructure object, such as a database instance. Managed
resources are cluster-scoped because they are only intended to be used directly
when an infrastructure admin is creating a single resource that is intended to
be shared across teams and namespaces. Infrastructure consumers, such as
application teams, are expected to _always_ provision and interact with
infrastructure via claims (XRCs).
<ul class="nav nav-tabs">
<li class="active"><a href="#aws-tab-1" data-toggle="tab">AWS</a></li>
<li><a href="#gcp-tab-1" data-toggle="tab">GCP</a></li>
<li><a href="#azure-tab-1" data-toggle="tab">Azure</a></li>
</ul>
<br>
<div class="tab-content">
<div class="tab-pane fade in active" id="aws-tab-1" markdown="1">
The AWS provider supports provisioning an [RDS] instance via the `RDSInstance`
managed resource it adds to Crossplane.
```yaml
apiVersion: database.aws.crossplane.io/v1beta1
kind: RDSInstance
metadata:
name: rdspostgresql
spec:
forProvider:
region: us-east-1
dbInstanceClass: db.t2.small
masterUsername: masteruser
allocatedStorage: 20
engine: postgres
engineVersion: "9.6"
skipFinalSnapshotBeforeDeletion: true
writeConnectionSecretToRef:
namespace: crossplane-system
name: aws-rdspostgresql-conn
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/provision/aws.yaml
```
Creating the above instance will cause Crossplane to provision an RDS instance
on AWS. You can view the progress with the following command:
```console
kubectl get rdsinstance rdspostgresql
```
When provisioning is complete, you should see `READY: True` in the output. You
can take a look at its connection secret that is referenced under `spec.writeConnectionSecretToRef`:
```console
kubectl describe secret aws-rdspostgresql-conn -n crossplane-system
```
You can then delete the `RDSInstance`:
```console
kubectl delete rdsinstance rdspostgresql
```
</div>
<div class="tab-pane fade" id="gcp-tab-1" markdown="1">
The GCP provider supports provisioning a [CloudSQL] instance with the
`CloudSQLInstance` managed resource it adds to Crossplane.
```yaml
apiVersion: database.gcp.crossplane.io/v1beta1
kind: CloudSQLInstance
metadata:
name: cloudsqlpostgresql
spec:
forProvider:
databaseVersion: POSTGRES_9_6
region: us-central1
settings:
tier: db-custom-1-3840
dataDiskType: PD_SSD
dataDiskSizeGb: 10
writeConnectionSecretToRef:
namespace: crossplane-system
name: cloudsqlpostgresql-conn
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/provision/gcp.yaml
```
Creating the above instance will cause Crossplane to provision a CloudSQL
instance on GCP. You can view the progress with the following command:
```console
kubectl get cloudsqlinstance cloudsqlpostgresql
```
When provisioning is complete, you should see `READY: True` in the output. You
can take a look at its connection secret that is referenced under `spec.writeConnectionSecretToRef`:
```console
kubectl describe secret cloudsqlpostgresql-conn -n crossplane-system
```
You can then delete the `CloudSQLInstance`:
```console
kubectl delete cloudsqlinstance cloudsqlpostgresql
```
</div>
<div class="tab-pane fade" id="azure-tab-1" markdown="1">
The Azure provider supports provisioning an [Azure Database for PostgreSQL]
instance with the `PostgreSQLServer` managed resource it adds to Crossplane.
> Note: provisioning an Azure Database for PostgreSQL requires the presence of a
> [Resource Group] in your Azure account. We go ahead and provision a new
> `ResourceGroup` here in case you do not already have a suitable one in your
> account.
```yaml
apiVersion: azure.crossplane.io/v1alpha3
kind: ResourceGroup
metadata:
name: sqlserverpostgresql-rg
spec:
location: West US 2
---
apiVersion: database.azure.crossplane.io/v1beta1
kind: PostgreSQLServer
metadata:
name: sqlserverpostgresql
spec:
forProvider:
administratorLogin: myadmin
resourceGroupNameRef:
name: sqlserverpostgresql-rg
location: West US 2
sslEnforcement: Disabled
version: "9.6"
sku:
tier: GeneralPurpose
capacity: 2
family: Gen5
storageProfile:
storageMB: 20480
writeConnectionSecretToRef:
namespace: crossplane-system
name: sqlserverpostgresql-conn
```
```console
kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/provision/azure.yaml
```
Creating the above instance will cause Crossplane to provision a PostgreSQL
database instance on Azure. You can view the progress with the following
command:
```console
kubectl get postgresqlserver sqlserverpostgresql
```
When provisioning is complete, you should see `READY: True` in the output. You
can take a look at its connection secret that is referenced under `spec.writeConnectionSecretToRef`:
```console
kubectl describe secret sqlserverpostgresql-conn -n crossplane-system
```
You can then delete the `PostgreSQLServer`:
```console
kubectl delete postgresqlserver sqlserverpostgresql
kubectl delete resourcegroup sqlserverpostgresql-rg
```
</div>
</div>
## Clean Up
Let's check whether there are any managed resources before deleting the
provider.
```console
kubectl get managed
```
If there are any, please delete them first, so you don't lose the track of them.
Then delete all the `ProviderConfig`s you created. An example command if you used
AWS Provider:
```
kubectl delete providerconfig.aws --all
```
List installed providers:
```console
kubectl get provider.pkg
```
Delete the one you want to delete:
```
kubectl delete provider.pkg <provider-name>
```
<!-- Named Links -->
[composition]: ../concepts/composition.md
[installed a provider]: ../concepts/providers.md
[configured your credentials]: ../concepts/providers.md
[RDS]: https://aws.amazon.com/rds/
[CloudSQL]: https://cloud.google.com/sql
[Azure Database for PostgreSQL]: https://azure.microsoft.com/en-us/services/postgresql/
[Resource Group]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal#what-is-a-resource-group
[ApsaraDB for RDS]: https://www.alibabacloud.com/product/apsaradb-for-rds-postgresql

8
docs/master/guides/guides.md
View File

@ -14,8 +14,10 @@ where Crossplane maintainers welcome guests from the cloud-native community and
show off [demos] integrating with the projects they work on. show off [demos] integrating with the projects they work on.
- [Upgrading to v0.14] - [Upgrading to v0.14]
- [Upgrading to v1.0] - [Upgrading to v1.x]
- [Vault Provider Credential Injection] - [Vault Provider Credential Injection]
- [Run Applications Using OAM]
- [Using Managed Resources Directly]
<!-- Named Links --> <!-- Named Links -->
@ -23,5 +25,7 @@ show off [demos] integrating with the projects they work on.
[The Binding Status]: https://youtube.com/playlist?list=PL510POnNVaaYFuK-B_SIUrpIonCtLVOzT [The Binding Status]: https://youtube.com/playlist?list=PL510POnNVaaYFuK-B_SIUrpIonCtLVOzT
[demos]: https://github.com/crossplane/tbs [demos]: https://github.com/crossplane/tbs
[Upgrading to v0.14]: upgrading-to-v0.14.md [Upgrading to v0.14]: upgrading-to-v0.14.md
[Upgrading to v1.0]: upgrading-to-v1.0.md [Upgrading to v1.x]: upgrading-to-v1.x.md
[Vault Provider Credential Injection]: vault-injection.md [Vault Provider Credential Injection]: vault-injection.md
[Run Applications Using OAM]: oam-applications.md
[Using Managed Resources Directly]: direct-managed.md

10
docs/master/getting-started/run-applications.md → docs/master/guides/oam-applications.md
View File

@ -1,7 +1,7 @@
--- ---
title: Run Applications title: OAM
toc: true toc: true
weight: 5 weight: 240
indent: true indent: true
--- ---
@ -474,7 +474,7 @@ kubectl delete -f https://raw.githubusercontent.com/crossplane/crossplane/master
[Open Application Model]: https://oam.dev/ [Open Application Model]: https://oam.dev/
[composing]: compose-infrastructure.md [composing]: compose-infrastructure.md
[Service Tracker Diagram]: run-applications-diagram.jpg [Service Tracker Diagram]: ../media/run-applications-diagram.jpg
[_workloads_]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/3.workload.md [_workloads_]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/3.workload.md
[_traits_]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/6.traits.md [_traits_]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/6.traits.md
[_components_]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/4.component.md [_components_]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/4.component.md
@ -482,5 +482,5 @@ kubectl delete -f https://raw.githubusercontent.com/crossplane/crossplane/master
[`ContainerizedWorkload`]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/core/workloads/containerized_workload/containerized_workload.md [`ContainerizedWorkload`]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/core/workloads/containerized_workload/containerized_workload.md
[`ManualScalerTrait`]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/core/traits/manual_scaler_trait.md [`ManualScalerTrait`]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/core/traits/manual_scaler_trait.md
[_application scope_]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/5.application_scopes.md [_application scope_]: https://github.com/oam-dev/spec/blob/1.0.0-alpha2/5.application_scopes.md
[Service Tracker Dashboard]: run-applications-dash.png [Service Tracker Dashboard]:../media/run-applications-dash.png
[Service Tracker Flights]: run-applications-flights.png [Service Tracker Flights]: ../media/run-applications-flights.png

22
docs/master/guides/upgrading-to-v1.0.md
View File

@ -1,22 +0,0 @@
---
title: Upgrading to v1.0
toc: true
weight: 220
indent: true
---
# Upgrading to v1.0
Crossplane v1.0 doesn't introduce any breaking changes, but it does make some
backward compatible changes to the core Crossplane CRDs. Helm [does not
currently touch CRDs](https://github.com/helm/helm/issues/6581) when a chart is
upgraded, so you must apply them manually before upgrading. To upgrade from
v0.14, run:
```console
# Update to the latest CRDs.
kubectl apply -k https://github.com/crossplane/crossplane//cluster?ref=release-1.0
# Update to the v1.0 Helm chart
helm --namespace crossplane-system upgrade crossplane crossplane-stable/crossplane
```

22
docs/master/guides/upgrading-to-v1.x.md Normal file
View File

@ -0,0 +1,22 @@
---
title: Upgrading to v1.x
toc: true
weight: 220
indent: true
---
# Upgrading to v1.x
Crossplane versions post v1.0 do not introduce any breaking changes, but may
make some backward compatible changes to the core Crossplane CRDs. Helm [does
not currently touch CRDs](https://github.com/helm/helm/issues/6581) when a chart
is upgraded, so you must apply them manually before upgrading. To upgrade from
the currently installed version, run:
```console
# Update to the latest CRDs.
kubectl apply -k https://github.com/crossplane/crossplane//cluster?ref=release-1.0
# Update to the latest stable Helm chart
helm --namespace crossplane-system upgrade crossplane crossplane-stable/crossplane
```

0
docs/master/getting-started/run-applications-dash.png → docs/master/media/run-applications-dash.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 212 KiB

After

Width:  |  Height:  |  Size: 212 KiB

0
docs/master/getting-started/run-applications-diagram.jpg → docs/master/media/run-applications-diagram.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 32 KiB

After

Width:  |  Height:  |  Size: 32 KiB

0
docs/master/getting-started/run-applications-flights.png → docs/master/media/run-applications-flights.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 841 KiB

After

Width:  |  Height:  |  Size: 841 KiB

2
docs/master/reference/learn_more.md
View File

@ -1,7 +1,7 @@
--- ---
title: Learn More title: Learn More
toc: true toc: true
weight: 304 weight: 305
indent: true indent: true
--- ---

9
docs/master/reference/overview.md
View File

@ -6,16 +6,23 @@ weight: 300
# Overview # Overview
The reference documentation includes answers to frequently asked questions, information about similar projects, and links to resources that can help you learn more about Crossplane and Kubernetes. If you have additional information that you think would be valuable for the community, please feel free to [open a pull request]() and add it. The reference documentation includes answers to frequently asked questions,
information about similar projects, and links to resources that can help you
learn more about Crossplane and Kubernetes. If you have additional information
that you think would be valuable for the community, please feel free to [open a
pull request] and add it.
1. [Install] 1. [Install]
1. [Configure] 1. [Configure]
1. [Uninstall]
1. [Troubleshoot] 1. [Troubleshoot]
1. [Learn More] 1. [Learn More]
<!-- Named Links --> <!-- Named Links -->
[open a pull request]: https://github.com/crossplane/crossplane/compare
[Install]: install.md [Install]: install.md
[Configure]: configure.md [Configure]: configure.md
[Uninstall]: uninstall.md
[Troubleshoot]: troubleshoot.md [Troubleshoot]: troubleshoot.md
[Learn More]: learn_more.md [Learn More]: learn_more.md

2
docs/master/reference/troubleshoot.md
View File

@ -1,7 +1,7 @@
--- ---
title: Troubleshoot title: Troubleshoot
toc: true toc: true
weight: 303 weight: 304
indent: true indent: true
--- ---

92
docs/master/reference/uninstall.md Normal file
View File

@ -0,0 +1,92 @@
---
title: Uninstall
toc: true
weight: 303
indent: true
---
# Uninstalling
Crossplane has a number of components that must be cleaned up in order to
guarantee proper removal from the cluster. When deleting objects, it is best to
consider parent-child relationships and clean up the children first to ensure
the proper action is taken externally. For instance, cleaning up `provider-aws`
before deleting an `RDSInstance` will result in the RDS instance remaining
provisioned on AWS as the controller responsible for cleaning it up will have
already been deleted. It will also result in the `RDSInstance` CRD remaining in
the cluster, which could make it difficult to re-install the same provider at a
future time.
## Deleting Resources
If you wish for all claims (XRC), composite resources (XR), and managed
resources to have deletion handled properly both in the cluster in externally,
they should be deleted and no longer exist in cluster before the package that
extended the Kubernetes API to include them is uninstalled. You can use the
following logic to clean up resources effectively:
- If an XRC exists for a given XR and set of managed resources, delete the XRC
and both the XR and managed resources will be cleaned up.
- If only an XR exists for a given set of managed resources, delete the XR and
each of the managed resources will be cleaned up.
- If a managed resource was provisioned directly, delete it directly.
The following commands can be used to identify existing XRC, XR, and managed
resources:
- XRC: `kubectl get claim`
- XR: `kubectl get composite`
- Managed Resources: `kubectl get managed`
Crossplane controllers add [finalizers] to resources to ensure they are handled
externally before they are fully removed from the cluster. If resource deletion
hangs it is likely due to a delay in the resource being handled externally,
causing the controller to wait to remove the finalizer. If this persists for a
long period of time, use the [troubleshooting guide] to fix the issue.
## Uninstall Packages
Once all resources are cleaned up, it is safe to uninstall packages.
`Configuration` packages can typically be deleted safely with the following
command:
```console
kubectl delete configuration.pkg <configuration-name>
```
Before deleting `Provider` packages, you will want to make sure you have deleted
all `ProviderConfig`s you created. An example command if you used AWS Provider:
```console
kubectl delete providerconfig.aws --all
```
Now you are safe to delete the `Provider` package:
```console
kubectl delete provider.pkg <provider-name>
```
## Uninstall Crossplane
When all resources and packages have been cleaned up, you are safe to uninstall
Crossplane:
```console
helm delete crossplane --namespace crossplane-system
kubectl delete namespace crossplane-system
```
Helm does not delete CRD objects. You can delete the ones Crossplane created
with the following commands:
```console
kubectl patch lock lock -p '{"metadata":{"finalizers": []}}' --type=merge
kubectl get crd -o name | grep crossplane.io | xargs kubectl delete
```
<!-- Named Links -->
[finalizers]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#finalizers
[troubleshooting guide]: troubleshoot.md

13
docs/master/snippets/compose/claim-alibaba.yaml
View File

@ -1,13 +0,0 @@
apiVersion: database.example.org/v1alpha1
kind: PostgreSQLInstance
metadata:
name: my-db
namespace: default
spec:
parameters:
storageGB: 20
compositionSelector:
matchLabels:
provider: alibaba
writeConnectionSecretToRef:
name: db-conn

13
docs/master/snippets/configure/alibaba/providerconfig.yaml
View File

@ -1,13 +0,0 @@
---
apiVersion: alibaba.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
name: default
spec:
region: cn-beijing
credentials:
source: Secret
secretRef:
namespace: crossplane-system
name: alibaba-creds
key: credentials

41
docs/master/snippets/package/alibaba/composition.yaml
View File

@ -1,41 +0,0 @@
---
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: compositepostgresqlinstances.alibaba.database.example.org
labels:
provider: alibaba
guide: quickstart
spec:
writeConnectionSecretsToNamespace: crossplane-system
compositeTypeRef:
apiVersion: database.example.org/v1alpha1
kind: CompositePostgreSQLInstance
resources:
- name: rdsinstance
base:
apiVersion: database.alibaba.crossplane.io/v1alpha1
kind: RDSInstance
spec:
forProvider:
engine: PostgreSQL
engineVersion: "9.4"
dbInstanceClass: rds.pg.s1.small
securityIPList: "0.0.0.0/0"
masterUsername: "myuser"
writeConnectionSecretToRef:
namespace: crossplane-system
patches:
- fromFieldPath: "metadata.uid"
toFieldPath: "spec.writeConnectionSecretToRef.name"
transforms:
- type: string
string:
fmt: "%s-postgresql"
- fromFieldPath: "spec.parameters.storageGB"
toFieldPath: "spec.forProvider.dbInstanceStorageInGB"
connectionDetails:
- fromConnectionSecretKey: username
- fromConnectionSecretKey: password
- fromConnectionSecretKey: endpoint
- fromConnectionSecretKey: port

13
docs/master/snippets/package/alibaba/crossplane.yaml
View File

@ -1,13 +0,0 @@
apiVersion: meta.pkg.crossplane.io/v1alpha1
kind: Configuration
metadata:
name: getting-started-with-alibaba
annotations:
guide: quickstart
provider: alibaba
spec:
crossplane:
version: ">=v0.14.0-0"
dependsOn:
- provider: crossplane/provider-alibaba
version: ">=v0.4.0"

38
docs/master/snippets/package/alibaba/definition.yaml
View File

@ -1,38 +0,0 @@
---
apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
name: compositepostgresqlinstances.database.example.org
spec:
group: database.example.org
names:
kind: CompositePostgreSQLInstance
plural: compositepostgresqlinstances
claimNames:
kind: PostgreSQLInstance
plural: postgresqlinstances
connectionSecretKeys:
- username
- password
- endpoint
- port
versions:
- name: v1alpha1
served: true
referenceable: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
properties:
parameters:
type: object
properties:
storageGB:
type: integer
required:
- storageGB
required:
- parameters

2
docs/master/snippets/package/aws-with-vpc/crossplane.yaml
View File

@ -8,7 +8,7 @@ metadata:
vpc: new vpc: new
spec: spec:
crossplane: crossplane:
version: ">=v0.14.0-0" version: ">=v1.0.0-0"
dependsOn: dependsOn:
- provider: crossplane/provider-aws - provider: crossplane/provider-aws
version: ">=v0.14.0" version: ">=v0.14.0"

2
docs/master/snippets/package/aws/crossplane.yaml
View File

@ -8,7 +8,7 @@ metadata:
vpc: default vpc: default
spec: spec:
crossplane: crossplane:
version: ">=v0.14.0-0" version: ">=v1.0.0-0"
dependsOn: dependsOn:
- provider: crossplane/provider-aws - provider: crossplane/provider-aws
version: ">=v0.14.0" version: ">=v0.14.0"

2
docs/master/snippets/package/azure/crossplane.yaml
View File

@ -7,7 +7,7 @@ metadata:
provider: azure provider: azure
spec: spec:
crossplane: crossplane:
version: ">=v0.14.0-0" version: ">=v1.0.0-0"
dependsOn: dependsOn:
- provider: crossplane/provider-azure - provider: crossplane/provider-azure
version: ">=v0.13.0" version: ">=v0.13.0"

2
docs/master/snippets/package/gcp/crossplane.yaml
View File

@ -7,7 +7,7 @@ metadata:
provider: gcp provider: gcp
spec: spec:
crossplane: crossplane:
version: ">=v0.14.0-0" version: ">=v1.0.0-0"
dependsOn: dependsOn:
- provider: crossplane/provider-gcp - provider: crossplane/provider-gcp
version: ">=v0.13.0" version: ">=v0.13.0"

15
docs/master/snippets/provision/alibaba.yaml
View File

@ -1,15 +0,0 @@
apiVersion: database.alibaba.crossplane.io/v1alpha1
kind: RDSInstance
metadata:
name: rdspostgresql
spec:
forProvider:
engine: PostgreSQL
engineVersion: "9.4"
dbInstanceClass: rds.pg.s1.small
dbInstanceStorageInGB: 20
securityIPList: "0.0.0.0/0"
masterUsername: "test123"
writeConnectionSecretToRef:
namespace: crossplane-system
name: alibaba-rdspostgresql-conn