docs snapshot for crossplane version `master`

docs/master/getting-started/install-configure.md

@@ -119,9 +119,10 @@ kubectl get all -n crossplane-system
 ```
 
 ## Install Crossplane CLI
-The [Crossplane CLI] adds a set of `kubectl crossplane` commands to simplify common tasks:
+
+The Crossplane CLI extends `kubectl` with functionality to build, push, and install [Crossplane packages]:
 ```
-curl -sL https://raw.githubusercontent.com/crossplane/crossplane-cli/master/bootstrap.sh | bash
+curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | sh
 ```
 
 ## Select Provider
@@ -139,10 +140,7 @@ Install and configure a provider for Crossplane to use for infrastructure provis
 ### Install AWS Provider
 
 ```
-PACKAGE=crossplane/provider-aws:master
+kubectl crossplane install provider crossplane/provider-aws:master
-NAME=provider-aws
-
-kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME}
 ```
 
 ### Get AWS Account Keyfile
@@ -161,7 +159,7 @@ kubectl create secret generic aws-creds -n crossplane-system --from-file=key=./c
 ### Configure the Provider
 Create the following `provider.yaml`:
 
-```
+```yaml
 apiVersion: aws.crossplane.io/v1beta1
 kind: ProviderConfig
 metadata:
@@ -184,10 +182,7 @@ kubectl apply -f provider.yaml
 ### Install GCP Provider
 
 ```
-PACKAGE=crossplane/provider-gcp:master
+kubectl crossplane install provider crossplane/provider-gcp:master
-NAME=provider-gcp
-
-kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME}
 ```
 
 ### Get GCP Account Keyfile
@@ -223,7 +218,7 @@ kubectl create secret generic gcp-creds -n crossplane-system --from-file=key=./c
 ### Configure the Provider
 Create the following `provider.yaml`:
 
-```
+```yaml
 apiVersion: gcp.crossplane.io/v1beta1
 kind: ProviderConfig
 metadata:
@@ -248,10 +243,7 @@ kubectl apply -f provider.yaml
 ### Install Azure Provider
 
 ```
-PACKAGE=crossplane/provider-azure:master
+kubectl crossplane install provider crossplane/provider-azure:master
-NAME=provider-azure
-
-kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME}
 ```
 
 ### Get Azure Principal Keyfile
@@ -286,7 +278,7 @@ kubectl create secret generic azure-creds -n crossplane-system --from-file=key=.
 ### Configure the Provider
 Create the following `provider.yaml`:
 
-```
+```yaml
 apiVersion: azure.crossplane.io/v1beta1
 kind: ProviderConfig
 metadata:
@@ -309,10 +301,7 @@ kubectl apply -f provider.yaml
 ### Install Alibaba Provider
 
 ```
-PACKAGE=crossplane/provider-alibaba:master
+kubectl crossplane install provider crossplane/provider-alibaba:master
-NAME=provider-alibaba
-
-kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME}
 ```
 
 ### Create a Provider Secret
@@ -324,7 +313,7 @@ kubectl create secret generic alibaba-creds --from-literal=accessKeyId=<your-key
 ### Configure the Provider
 Create the following `provider.yaml`:
 
-```
+```yaml
 apiVersion: alibaba.crossplane.io/v1alpha1
 kind: Provider
 metadata:
@@ -380,4 +369,4 @@ kubectl delete namespace crossplane-system
 [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 CLI]: https://github.com/crossplane/crossplane-cli
+[Crossplane packages]: ../introduction/packages.md

docs/master/introduction/packages.md

@@ -0,0 +1,256 @@
+---
+title: Packages
+toc: true
+weight: 104
+indent: true
+---
+
+# Crossplane Packages
+
+Crossplane packages are opinionated [OCI images] that contain a stream of YAML
+that can be parsed by the Crossplane package manager. Crossplane packages come
+in two varieties: [Providers] and Configurations. Ultimately, the primary
+purposes of Crossplane packages are as follows:
+
+- **Convenient Distribution**: Crossplane packages can be pushed to or installed
+  from any OCI-compatible registry.
+- **Version Upgrade**: Crossplane can update packages in-place, meaning that you
+  can pick up support for new resource types or controller bug-fixes without
+  modifying your existing infrastructure.
+- **Permissions**: Crossplane allocates permissions to packaged controllers in a
+  manner that ensures they will not maliciously take over control of existing
+  resources owned by other packages. Installing CRDs via packages also allows
+  Crossplane itself to manage those resources, allowing for powerful
+  [composition] features to be enabled.
+- **Dependency Management**: In future releases, Crossplane will be able to
+  resolve dependencies between packages, automatically installing a package's
+  dependencies if they are not present in the cluster.
+
+## Building a Package
+
+As stated above, Crossplane packages are just opinionated OCI images, meaning
+they can be constructed using any tool that outputs files that comply the the
+OCI specification. However, constructing packages using the Crossplane CLI is a
+more streamlined experience, as it will performing build-time checks on your
+packages to ensure that they are compliant with the Crossplane [package format].
+
+Providers and Configurations vary in the types of resources they may contain in
+their packages. All packages must have a `crossplane.yaml` file in the root
+directory with package contents. The `crossplane.yaml` contains the package's
+metadata, which governs how Crossplane will install the package.
+
+### Provider Packages
+
+A Provider package contains a `crossplane.yaml` with the following format:
+
+```yaml
+apiVersion: meta.pkg.crossplane.io/v1alpha1
+kind: Provider
+metadata:
+  name: provider-gcp
+spec:
+  controller:
+    image: crossplane/provider-gcp-controller:master
+```
+
+> Note: The `meta.pkg.crossplane.io` group does contain actual CRDs that get
+> installed into the cluster. They are strictly used as metadata in a Crossplane
+> package.
+
+The `spec.controller.image` fields specifies that the `Provider` desires for a
+`Deployment` to be created with the provided image. It is important to note that
+this image is separate from the package image itself. In the case above, it is
+an image containing the `provider-gcp` controller binary.
+
+A Provider package may optionally contain one or more CRDs. These CRDs will be
+installed prior to the creation of the Provider's `Deployment`. Crossplane will
+not install _any_ CRDs for a package unless it can determine that _all_ CRDs can
+be installed. This guards against multiple Providers attempting to reconcile the
+same CRDs. Crossplane will also create a `ServiceAccount` with permissions to
+reconcile these CRDs and it will be assigned to the controller `Deployment`.
+
+For an example Provider package, see [provider-gcp].
+
+To build a Provider package, navigate to the package root directory and execute
+the following command:
+
+```
+kubectl crossplane build provider
+```
+
+If the Provider package is valid, you will see a file with the `.xpkg`
+extension.
+
+### Configuration Packages
+
+A Configuration package contains a `crossplane.yaml` with the following format:
+
+```yaml
+apiVersion: meta.pkg.crossplane.io/v1alpha1
+kind: Configuration
+metadata:
+  name: my-org-infra
+```
+
+Currently, the only purpose of a Configuration's `crossplane.yaml` is to declare
+that it is in fact a Configuration package type. However, future releases will
+include additional fields for functionality such as specifying dependencies on
+Provider packages.
+
+A Configuration package may also specify one or more of
+`CompositeResourceDefinition` and `Composition` types. These resources will be
+installed and will be solely owned by the Configuration package. No other
+package will be able to modify them.
+
+To build a Configuration package, navigate to the package root directory and
+execute the following command:
+
+```
+kubectl crossplane build configuration
+```
+
+If the Provider package is valid, you will see a file with the `.xpkg`
+extension.
+
+## Pushing a Package
+
+Crossplane packages can be pushed to any OCI-compatible registry. If a specific
+registry is not specified they will be pushed to Docker Hub.
+
+To push a Provider package, execute the following command:
+
+```
+kubectl crossplane push provider crossplane/provider-gcp:master
+```
+
+To push a Configuration package, execute the following command:
+
+```
+kubectl crossplane push provider crossplane/my-org-infra:master
+```
+
+> Note: Both of the above commands assume a single `.xpkg` file exists in the
+> directory. If multiple exist or you would like to specify a package in a
+> different directory, you can supply the `-f` flag with the path to the
+> package.
+
+## Installing a Package
+
+Packages can be installed into a Crossplane cluster using the Crossplane CLI.
+
+To install a Provider package, execute the following command:
+
+```
+kubectl crossplane install provider crossplane/provider-gcp:master
+```
+
+To install a Configuration package, execute the following command:
+
+```
+kubectl crossplane install configuration crossplane/my-org-infra:master
+```
+
+Packages can also be installed manually by creating a `Provider` or
+`Configuration` object directly. The preceding commands would result in the
+creation of the following two resources, which could have been authored by hand:
+
+```yaml
+apiVersion: pkg.crossplane.io/v1alpha1
+kind: Provider
+metadata:
+  name: provider-gcp
+spec:
+  package: crossplane/provider-gcp:master
+  revisionActivationPolicy: Automatic
+  revisionHistoryLimit: 1
+```
+
+```yaml
+apiVersion: pkg.crossplane.io/v1alpha1
+kind: Configuration
+metadata:
+  name: provider-gcp
+spec:
+  package: crossplane/provider-gcp:master
+  revisionActivationPolicy: Automatic
+  revisionHistoryLimit: 1
+```
+
+> Note: These types differ from the `Provider` and `Configuration` types we saw
+> earlier. They exist in the `pkg.crossplane.io` group rather than the
+> `meta.pkg.crossplane.io` group and are actual CRD types installed in the
+> cluster.
+
+The `spec.revisionActivationPolicy` and `spec.revisionHistoryLimit` fields are
+explained in the following section.
+
+## Upgrading a Package
+
+Once a package is installed, Crossplane makes it easy to upgrade to a new
+version. Controlling this functionality is accomplished via the three `spec`
+fields shown above. They are explained in detail below.
+
+### spec.package
+
+This is the package image that we built, pushed, and are asking Crossplane to
+install. The tag we specify here is important. Crossplane will periodically
+check if the installed image matches the digest of the image in the remote
+registry. If it does not, Crossplane will create a new _Revision_ (either
+`ProviderRevision` or `ConfigurationRevision`). If you do not for Crossplane to
+ever update your packages without explicitly instructing it to do so, you should
+consider specifying a tag which you know will not have the underlying contents
+change unexpectedly (e.g. a specific semantic version, such as `v0.1.0`) or, for
+an even stronger guarantee, providing the image with a `@sha256` extension
+instead of a tag.
+
+### spec.revisionActivationPolicy
+
+Valid values: `Automatic` or `Manual` (default: `Automatic`)
+
+This field determines what Crossplane does when a new revision is created, be it
+manually by you specifying a new tag in the `spec.package` field, or
+automatically if a general tag such as `latest` or `master` is used and the
+underlying contents change. When a new revision is created for a package, it can
+either be `Active` or `Inactive`.
+
+An `Active` package revision attempts to become the _controller_ of all
+resources it installs. There can only be one controller of a resource, so if two
+`Active` revisions both install the same resource, one will fail to install
+until the other cedes control.
+
+An `Inactive` package revision attempts to become the _owner_ of all resource it
+installs. There can be an arbitrary number of owners of a resource, so multiple
+`Inactive` revisions and a single `Active` revisions can exist for a resource.
+Importantly, an `Inactive` package revision will not perform any auxiliary
+actions (such as creating a `Deployment` in the case of a `Provider`), meaning
+we will not encounter a situation where two revisions are fighting over
+reconciling a resource.
+
+### spec.revisionHistoryLimit
+
+Valid values: any integer, disabled by explicitly setting to `0` (default `1`)
+
+When a revision transitions from `Inactive` to `Active`, its revision number
+gets set to one greater than the largest revision number of all revisions for
+its package. Therefore, as the number of revisions increases, the least recently
+`Active` revision will have the lowest revision number. Crossplane will garbage
+collect old `Inactive` revisions if they fall outside the
+`spec.revisionHistoryLimit`. For instance, if my revision history limit is `3`
+and I currently have three old `Inactive` revisions and one `Active` revision,
+when I upgrade the next time, the new revision will be given the highest
+revision number when it becomes `Active`, the previously `Active` revision will
+become `Inactive`, and the oldest `Inactive` revision will be garbage collected.
+
+> Note: In the case that `spec.revisionActivationPolicy: Manual` and you upgrade
+> enough times (but do not make `Active` the new revisions), it is possible that
+> activating a newer revision could cause the previously `Active` revision to
+> immediately be garbage collected if it is outside the
+> `spec.revisionHistoryLimit`. 
+
+<!-- Named Links -->
+
+[OCI images]: https://github.com/opencontainers/image-spec
+[Providers]: providers.md
+[composition]: composition.md
+[package format]: https://github.com/crossplane/crossplane/blob/1aa83092172bdf0d2ed64754d33517c612ff7368/design/one-pager-package-format-v2.md
+[provider-gcp]: https://github.com/crossplane/provider-gcp/tree/master/package

docs/master/introduction/providers.md

@@ -7,11 +7,11 @@ indent: true
 
 # Providers
 
-Providers extend Crossplane to enable infrastructure resource provisioning.
+Providers extend Crossplane to enable infrastructure resource provisioning. In
-In order to provision a resource, a Custom Resource Definition(CRD)
+order to provision a resource, a Custom Resource Definition (CRD) needs to be
-needs to be registered in your Kubernetes cluster and its controller should
+registered in your Kubernetes cluster and its controller should be watching the
-be watching the Custom Resources those CRDs define. Provider packages
+Custom Resources those CRDs define. Provider packages contain many Custom
-contain many Custom Resource Definitions and their controllers.
+Resource Definitions and their controllers.
 
 Here is the list of current providers:
 
@@ -64,13 +64,10 @@ and set up necessary RBAC rules and then start the controllers.
 There are a few other ways to to trigger the installation of provider packages:
 
 * As part of Crossplane Helm chart by adding the following statement to your
-  `helm install` command: `--set clusterPackages.gcp.deploy=true` It will
+  `helm install` command: `--set
-  install the default version hard-coded in that release of Crossplane Helm
+  provider.packages={crossplane/provider-aws:master}`.
-  chart but if you'd like to specif an exact version, you can add: `--set
+* Using the Crossplane CLI: `kubectl crossplane install provider
-  clusterPackages.gcp.version=master`.
+  crossplane/provider-aws:master`
-* Using [Crossplane kubectl plugin][crossplane-cli]: `kubectl crossplane package
-  install --cluster -n crossplane-system 'crossplane/provider-gcp:master'
-  provider-gcp`
 
 You can uninstall a provider by deleting the `ClusterPackageInstall` resource
 you've created.
@@ -136,4 +133,3 @@ will attempt to use a `ProviderConfig` named `default`.
 [provider-alibaba]: https://github.com/crossplane/provider-alibaba
 [alibaba-reference]: https://doc.crds.dev/github.com/crossplane/provider-alibaba
 [getting-started]: ../getting-started/install-configure.md
-[crossplane-cli]: https://github.com/crossplane/crossplane-cli