diff --git a/docs/master/getting-started/compose-infrastructure.md b/docs/master/getting-started/compose-infrastructure.md deleted file mode 100644 index 6f833b9b..00000000 --- a/docs/master/getting-started/compose-infrastructure.md +++ /dev/null @@ -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. - - -
-
-
- -> 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 -``` - -
-
- -> 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 -``` - -
-
- -```console -kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-gcp:latest -``` - -
-
- -```console -kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-azure:latest -``` - -
-
- -```console -kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-alibaba:latest -``` - -
-
- -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! - - -
-
-
- -```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 -``` - -
-
- -```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 -``` - -
-
- -```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 -``` - -
-
- -```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 -``` - -
-
- -```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 -``` - -
-
- -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 `: get all resources related to ``. -> - `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. - - - -[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/ diff --git a/docs/master/getting-started/package-infrastructure.md b/docs/master/getting-started/create-configuration.md similarity index 87% rename from docs/master/getting-started/package-infrastructure.md rename to docs/master/getting-started/create-configuration.md index 4abe164d..a121a83b 100644 --- a/docs/master/getting-started/package-infrastructure.md +++ b/docs/master/getting-started/create-configuration.md @@ -1,35 +1,24 @@ --- -title: Package Infrastructure +title: Create a Configuration toc: true -weight: 6 +weight: 4 indent: true --- -# Package Infrastructure +# Create a Configuration -In a [previous section] we learned that Crossplane can be configured with new -composite resources (XRs) that are [composed] of other resources, allowing you -to define and offer resources that group and abstract infrastructure primitives. -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] 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`. +In the [previous section] we were able to create a PostgreSQL database because +we had installed a configuration package that defined the `PostgreSQLInstance` +type and a `Composition` of managed resources that mapped to it. Crossplane +allows you to define your own composite resources (XRs) and compositions, then +package them up to be easily distributed as OCI images. This allows you to +construct a reproducible platform that exposes infrastructure APIs at your +desired level of abstraction, and can be installed into any Crossplane cluster. ## 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. * `definition.yaml` - The XRD. @@ -53,6 +42,10 @@ cd crossplane-config We'll create the aforementioned three files in this directory, then build them 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 First we'll create a `CompositeResourceDefinition` (XRD) to define the schema of @@ -119,7 +112,6 @@ instance on the chosen provider.
  • AWS (New VPC)
  • GCP
  • Azure
    • -
  • Alibaba

    • @@ -563,7 +555,6 @@ so that Crossplane users may install it.
  • AWS (New VPC)
  • GCP
  • Azure
    • -
  • Alibaba

    • @@ -578,15 +569,28 @@ metadata: guide: quickstart provider: aws vpc: default +spec: + crossplane: + version: ">=v1.0.0-0" + dependsOn: + - provider: crossplane/provider-aws + version: ">=v0.14.0" ``` ```console 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. REG=my-package-repo - -kubectl crossplane build configuration kubectl crossplane push configuration ${REG}/getting-started-with-aws:master ``` @@ -605,15 +609,28 @@ metadata: guide: quickstart provider: aws vpc: new +spec: + crossplane: + version: ">=v1.0.0-0" + dependsOn: + - provider: crossplane/provider-aws + version: ">=v0.14.0" ``` ```console 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. REG=my-package-repo - -kubectl crossplane build configuration kubectl crossplane push configuration ${REG}/getting-started-with-aws-with-vpc:master ``` @@ -631,15 +648,28 @@ metadata: annotations: guide: quickstart provider: gcp +spec: + crossplane: + version: ">=v1.0.0-0" + dependsOn: + - provider: crossplane/provider-gcp + version: ">=v0.13.0" ``` ```console 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. REG=my-package-repo - -kubectl crossplane build configuration kubectl crossplane push configuration ${REG}/getting-started-with-gcp:master ``` @@ -657,42 +687,29 @@ metadata: annotations: guide: quickstart provider: azure +spec: + crossplane: + version: ">=v1.0.0-0" + dependsOn: + - provider: crossplane/provider-azure + version: ">=v0.13.0" ``` ```console 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 push configuration ${REG}/getting-started-with-azure:master ``` -> Note that the Crossplane CLI will not follow symbolic links for files in the -> root package directory. - -
    -
    - -```yaml -apiVersion: meta.pkg.crossplane.io/v1 -kind: Configuration -metadata: - name: getting-started-with-alibaba - annotations: - guide: quickstart - provider: alibaba -``` +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 -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. REG=my-package-repo - -kubectl crossplane build configuration -kubectl crossplane push configuration ${REG}/getting-started-with-alibaba:master +kubectl crossplane push configuration ${REG}/getting-started-with-azure:master ``` > 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 Crossplane [packages] documentation for more information about installing and -working with packages. +working with packages, or read about other Crossplane [concepts]. ## Clean Up @@ -716,9 +733,9 @@ rm -rf crossplane-config -[previous section]: compose-infrastructure.md +[previous section]: provision-infrastructure.md [composed]: ../concepts/composition.md [composition]: ../concepts/composition.md [Docker Hub]: https://hub.docker.com/ [packages]: ../concepts/packages.md -[packaged]: ../concepts/packages.md +[concepts]: ../concepts/overview.md diff --git a/docs/master/getting-started/install-configure.md b/docs/master/getting-started/install-configure.md index e1b99013..0c93177e 100644 --- a/docs/master/getting-started/install-configure.md +++ b/docs/master/getting-started/install-configure.md @@ -201,29 +201,58 @@ curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.
    -## 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:
    -
    +
    -### 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 -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 @@ -237,7 +266,7 @@ AWS_PROFILE=default && echo -e "[default]\naws_access_key_id = $(aws configure g ### Create a Provider Secret ```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 @@ -256,24 +285,82 @@ spec: secretRef: namespace: crossplane-system name: aws-creds - key: key + key: creds ``` ```console kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/aws/providerconfig.yaml ```
    -
    +
    -### 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 -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 +``` + +
    +
    + +### 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 @@ -303,7 +390,7 @@ gcloud iam service-accounts keys create creds.json --project $PROJECT_ID --iam-a ### Create a Provider Secret ```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 @@ -325,21 +412,25 @@ spec: secretRef: namespace: crossplane-system name: gcp-creds - key: key" | kubectl apply -f - + key: creds" | kubectl apply -f - ```
    -
    +
    -### 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 -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 @@ -368,7 +459,7 @@ az ad app permission admin-consent --id "${AZURE_CLIENT_ID}" ### Create a Provider Secret ```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 @@ -387,120 +478,39 @@ spec: secretRef: namespace: crossplane-system name: azure-creds - key: key + key: creds ``` ```console kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/azure/providerconfig.yaml ``` -
    -
    - -### 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 and with your actual key id and key secret. -kubectl create secret generic alibaba-creds --from-literal=accessKeyId= --from-literal=accessKeySecret= -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 -``` -
    ## 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 See [Install] and [Configure] docs for installing alternate versions and more detailed instructions. -## Uninstall Provider - -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 -``` - -## 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 -``` +See [Uninstall] docs for cleaning up resources, packages, and Crossplane itself. -[provision infrastructure]: provision-infrastructure.md -[Install]: ../reference/install.md -[Configure]: ../reference/configure.md -[Kubernetes cluster]: https://kubernetes.io/docs/setup/ -[Minikube]: https://kubernetes.io/docs/tasks/tools/install-minikube/ -[Helm]:https://docs.helm.sh/using_helm/ -[Kind]: https://kind.sigs.k8s.io/docs/user/quick-start/ -[Crossplane packages]: ../concepts/packages.md +[package]: ../concepts/packages.md +[provision infrastructure]: provision-infrastructure.md +[create a configuration]: create-configuration.md +[Install]: ../reference/install.md +[Configure]: ../reference/configure.md +[Uninstall]: ../reference/uninstall.md +[Kubernetes cluster]: https://kubernetes.io/docs/setup/ +[Minikube]: https://kubernetes.io/docs/tasks/tools/install-minikube/ +[Helm]:https://docs.helm.sh/using_helm/ +[Kind]: https://kind.sigs.k8s.io/docs/user/quick-start/ +[Crossplane packages]: ../concepts/packages.md [Slack]: http://slack.crossplane.io/ -[Upbound Cloud]: https://upbound.io \ No newline at end of file +[Upbound Cloud]: https://upbound.io diff --git a/docs/master/getting-started/provision-infrastructure.md b/docs/master/getting-started/provision-infrastructure.md index 2334189b..d2bdb028 100644 --- a/docs/master/getting-started/provision-infrastructure.md +++ b/docs/master/getting-started/provision-infrastructure.md @@ -7,252 +7,277 @@ indent: true # Provision Infrastructure -Crossplane allows you to provision infrastructure anywhere using the Kubernetes -API. 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. +Composite resources (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. 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 -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. +## Claim Your Infrastructure + +The `Configuration` package we installed in the last section: + +- 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!
    -
    +
    -The AWS provider supports provisioning an [RDS] instance via the `RDSInstance` -managed resource it adds to Crossplane. +> Note that this resource 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. ```yaml -apiVersion: database.aws.crossplane.io/v1beta1 -kind: RDSInstance +apiVersion: database.example.org/v1alpha1 +kind: PostgreSQLInstance metadata: - name: rdspostgresql + name: my-db + namespace: default spec: - forProvider: - region: us-east-1 - dbInstanceClass: db.t2.small - masterUsername: masteruser - allocatedStorage: 20 - engine: postgres - engineVersion: "9.6" - skipFinalSnapshotBeforeDeletion: true + parameters: + storageGB: 20 + compositionSelector: + matchLabels: + provider: aws + vpc: default writeConnectionSecretToRef: - namespace: crossplane-system - name: aws-rdspostgresql-conn + name: db-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 +kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-aws.yaml ```
    -
    +
    -The GCP provider supports provisioning a [CloudSQL] instance with the -`CloudSQLInstance` managed resource it adds to Crossplane. +> Note that this resource 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. ```yaml -apiVersion: database.gcp.crossplane.io/v1beta1 -kind: CloudSQLInstance +apiVersion: database.example.org/v1alpha1 +kind: PostgreSQLInstance metadata: - name: cloudsqlpostgresql + name: my-db + namespace: default spec: - forProvider: - databaseVersion: POSTGRES_9_6 - region: us-central1 - settings: - tier: db-custom-1-3840 - dataDiskType: PD_SSD - dataDiskSizeGb: 10 + parameters: + storageGB: 20 + compositionSelector: + matchLabels: + provider: aws + vpc: new writeConnectionSecretToRef: - namespace: crossplane-system - name: cloudsqlpostgresql-conn + name: db-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 +kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-aws.yaml ```
    -
    - -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 +apiVersion: database.example.org/v1alpha1 +kind: PostgreSQLInstance metadata: - name: sqlserverpostgresql-rg + name: my-db + namespace: default 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 + parameters: + storageGB: 20 + compositionSelector: + matchLabels: + provider: gcp writeConnectionSecretToRef: - namespace: crossplane-system - name: sqlserverpostgresql-conn + name: db-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 +kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-gcp.yaml ```
    -
    - -The Alibaba provider supports provisioning an [ApsaraDB for RDS] instance with -the `RDSInstance` managed resource it adds to Crossplane. +
    ```yaml -apiVersion: database.alibaba.crossplane.io/v1alpha1 -kind: RDSInstance +apiVersion: database.example.org/v1alpha1 +kind: PostgreSQLInstance metadata: - name: rdspostgresql + name: my-db + namespace: default spec: - forProvider: - engine: PostgreSQL - engineVersion: "9.4" - dbInstanceClass: rds.pg.s1.small - dbInstanceStorageInGB: 20 - securityIPList: "0.0.0.0/0" - masterUsername: "test123" + parameters: + storageGB: 20 + compositionSelector: + matchLabels: + provider: azure writeConnectionSecretToRef: - namespace: crossplane-system - name: alibaba-rdspostgresql-conn + name: db-conn ``` ```console -kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/provision/alibaba.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 +kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/compose/claim-azure.yaml ```
    +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 `: get all resources related to ``. +> - `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 -Now that you have seen how to provision individual managed resources, let's take -a look at how we can compose several managed resources into new resources with -APIs of our choosing in the [next section]. +Now you have seen how to provision and consume complex infrastructure via +composition. In the [next section] you will learn how compose and package your +own infrastructure APIs. -[installed a provider]: install-configure.md -[configured your credentials]: install-configure.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 -[next section]: compose-infrastructure.md +[Persistent Volumes (PV) and Persistent Volume Claims (PVC)]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/ +[composition]: ../concepts/composition.md +[setup]: install-configure.md +[next section]: create-configuration.md diff --git a/docs/master/guides/direct-managed.md b/docs/master/guides/direct-managed.md new file mode 100644 index 00000000..7df5153d --- /dev/null +++ b/docs/master/guides/direct-managed.md @@ -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). + + +
    +
    +
    + +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 +``` + +
    +
    + +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 +``` + +
    +
    + +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 +``` + +
    +
    + +## 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 +``` + + + +[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 diff --git a/docs/master/guides/guides.md b/docs/master/guides/guides.md index 09a2391c..64e89630 100644 --- a/docs/master/guides/guides.md +++ b/docs/master/guides/guides.md @@ -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. - [Upgrading to v0.14] -- [Upgrading to v1.0] +- [Upgrading to v1.x] - [Vault Provider Credential Injection] +- [Run Applications Using OAM] +- [Using Managed Resources Directly] @@ -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 [demos]: https://github.com/crossplane/tbs [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 +[Run Applications Using OAM]: oam-applications.md +[Using Managed Resources Directly]: direct-managed.md diff --git a/docs/master/getting-started/run-applications.md b/docs/master/guides/oam-applications.md similarity index 98% rename from docs/master/getting-started/run-applications.md rename to docs/master/guides/oam-applications.md index 2189042e..a7a14666 100644 --- a/docs/master/getting-started/run-applications.md +++ b/docs/master/guides/oam-applications.md @@ -1,7 +1,7 @@ --- -title: Run Applications +title: OAM toc: true -weight: 5 +weight: 240 indent: true --- @@ -474,7 +474,7 @@ kubectl delete -f https://raw.githubusercontent.com/crossplane/crossplane/master [Open Application Model]: https://oam.dev/ [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 [_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 @@ -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 [`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 -[Service Tracker Dashboard]: run-applications-dash.png -[Service Tracker Flights]: run-applications-flights.png +[Service Tracker Dashboard]:../media/run-applications-dash.png +[Service Tracker Flights]: ../media/run-applications-flights.png diff --git a/docs/master/guides/upgrading-to-v1.0.md b/docs/master/guides/upgrading-to-v1.0.md deleted file mode 100644 index e273c9b6..00000000 --- a/docs/master/guides/upgrading-to-v1.0.md +++ /dev/null @@ -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 -``` \ No newline at end of file diff --git a/docs/master/guides/upgrading-to-v1.x.md b/docs/master/guides/upgrading-to-v1.x.md new file mode 100644 index 00000000..b291f5f4 --- /dev/null +++ b/docs/master/guides/upgrading-to-v1.x.md @@ -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 +``` \ No newline at end of file diff --git a/docs/master/getting-started/run-applications-dash.png b/docs/master/media/run-applications-dash.png similarity index 100% rename from docs/master/getting-started/run-applications-dash.png rename to docs/master/media/run-applications-dash.png diff --git a/docs/master/getting-started/run-applications-diagram.jpg b/docs/master/media/run-applications-diagram.jpg similarity index 100% rename from docs/master/getting-started/run-applications-diagram.jpg rename to docs/master/media/run-applications-diagram.jpg diff --git a/docs/master/getting-started/run-applications-flights.png b/docs/master/media/run-applications-flights.png similarity index 100% rename from docs/master/getting-started/run-applications-flights.png rename to docs/master/media/run-applications-flights.png diff --git a/docs/master/reference/learn_more.md b/docs/master/reference/learn_more.md index 75bd883e..7b1377d8 100644 --- a/docs/master/reference/learn_more.md +++ b/docs/master/reference/learn_more.md @@ -1,7 +1,7 @@ --- title: Learn More toc: true -weight: 304 +weight: 305 indent: true --- diff --git a/docs/master/reference/overview.md b/docs/master/reference/overview.md index 9f3a4a15..811e7c29 100644 --- a/docs/master/reference/overview.md +++ b/docs/master/reference/overview.md @@ -6,16 +6,23 @@ weight: 300 # 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. [Configure] +1. [Uninstall] 1. [Troubleshoot] 1. [Learn More] +[open a pull request]: https://github.com/crossplane/crossplane/compare [Install]: install.md [Configure]: configure.md +[Uninstall]: uninstall.md [Troubleshoot]: troubleshoot.md [Learn More]: learn_more.md diff --git a/docs/master/reference/troubleshoot.md b/docs/master/reference/troubleshoot.md index cf42dffb..b7944f30 100644 --- a/docs/master/reference/troubleshoot.md +++ b/docs/master/reference/troubleshoot.md @@ -1,7 +1,7 @@ --- title: Troubleshoot toc: true -weight: 303 +weight: 304 indent: true --- diff --git a/docs/master/reference/uninstall.md b/docs/master/reference/uninstall.md new file mode 100644 index 00000000..0a7a66b6 --- /dev/null +++ b/docs/master/reference/uninstall.md @@ -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 +``` + +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 +``` + +## 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 +``` + + + +[finalizers]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#finalizers +[troubleshooting guide]: troubleshoot.md diff --git a/docs/master/snippets/compose/claim-alibaba.yaml b/docs/master/snippets/compose/claim-alibaba.yaml deleted file mode 100644 index 2214b1a1..00000000 --- a/docs/master/snippets/compose/claim-alibaba.yaml +++ /dev/null @@ -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 diff --git a/docs/master/snippets/configure/alibaba/providerconfig.yaml b/docs/master/snippets/configure/alibaba/providerconfig.yaml deleted file mode 100644 index 1a8bdd95..00000000 --- a/docs/master/snippets/configure/alibaba/providerconfig.yaml +++ /dev/null @@ -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 diff --git a/docs/master/snippets/package/alibaba/composition.yaml b/docs/master/snippets/package/alibaba/composition.yaml deleted file mode 100644 index 8eaae3b1..00000000 --- a/docs/master/snippets/package/alibaba/composition.yaml +++ /dev/null @@ -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 diff --git a/docs/master/snippets/package/alibaba/crossplane.yaml b/docs/master/snippets/package/alibaba/crossplane.yaml deleted file mode 100644 index 20f2a3f3..00000000 --- a/docs/master/snippets/package/alibaba/crossplane.yaml +++ /dev/null @@ -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" diff --git a/docs/master/snippets/package/alibaba/definition.yaml b/docs/master/snippets/package/alibaba/definition.yaml deleted file mode 100644 index 995622d8..00000000 --- a/docs/master/snippets/package/alibaba/definition.yaml +++ /dev/null @@ -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 diff --git a/docs/master/snippets/package/aws-with-vpc/crossplane.yaml b/docs/master/snippets/package/aws-with-vpc/crossplane.yaml index 540fd556..39423ecd 100644 --- a/docs/master/snippets/package/aws-with-vpc/crossplane.yaml +++ b/docs/master/snippets/package/aws-with-vpc/crossplane.yaml @@ -8,7 +8,7 @@ metadata: vpc: new spec: crossplane: - version: ">=v0.14.0-0" + version: ">=v1.0.0-0" dependsOn: - provider: crossplane/provider-aws version: ">=v0.14.0" diff --git a/docs/master/snippets/package/aws/crossplane.yaml b/docs/master/snippets/package/aws/crossplane.yaml index fc7cafaf..732827ae 100644 --- a/docs/master/snippets/package/aws/crossplane.yaml +++ b/docs/master/snippets/package/aws/crossplane.yaml @@ -8,7 +8,7 @@ metadata: vpc: default spec: crossplane: - version: ">=v0.14.0-0" + version: ">=v1.0.0-0" dependsOn: - provider: crossplane/provider-aws version: ">=v0.14.0" diff --git a/docs/master/snippets/package/azure/crossplane.yaml b/docs/master/snippets/package/azure/crossplane.yaml index b26c808c..570ea7cc 100644 --- a/docs/master/snippets/package/azure/crossplane.yaml +++ b/docs/master/snippets/package/azure/crossplane.yaml @@ -7,7 +7,7 @@ metadata: provider: azure spec: crossplane: - version: ">=v0.14.0-0" + version: ">=v1.0.0-0" dependsOn: - provider: crossplane/provider-azure version: ">=v0.13.0" diff --git a/docs/master/snippets/package/gcp/crossplane.yaml b/docs/master/snippets/package/gcp/crossplane.yaml index 75a32673..85c46eb8 100644 --- a/docs/master/snippets/package/gcp/crossplane.yaml +++ b/docs/master/snippets/package/gcp/crossplane.yaml @@ -7,7 +7,7 @@ metadata: provider: gcp spec: crossplane: - version: ">=v0.14.0-0" + version: ">=v1.0.0-0" dependsOn: - provider: crossplane/provider-gcp version: ">=v0.13.0" diff --git a/docs/master/snippets/provision/alibaba.yaml b/docs/master/snippets/provision/alibaba.yaml deleted file mode 100644 index 045e3c20..00000000 --- a/docs/master/snippets/provision/alibaba.yaml +++ /dev/null @@ -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