diff --git a/docs/master/getting-started/install-configure.md b/docs/master/getting-started/install-configure.md index ef57a8b6..64d1c993 100644 --- a/docs/master/getting-started/install-configure.md +++ b/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 -NAME=provider-aws - -kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME} +kubectl crossplane install provider crossplane/provider-aws:master ``` ### 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 -NAME=provider-gcp - -kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME} +kubectl crossplane install provider crossplane/provider-gcp:master ``` ### 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 -NAME=provider-azure - -kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME} +kubectl crossplane install provider crossplane/provider-azure:master ``` ### 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 -NAME=provider-alibaba - -kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME} +kubectl crossplane install provider crossplane/provider-alibaba:master ``` ### Create a Provider Secret @@ -324,7 +313,7 @@ kubectl create secret generic alibaba-creds --from-literal=accessKeyId= 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`. + + + +[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 diff --git a/docs/master/introduction/providers.md b/docs/master/introduction/providers.md index 69ee0cf5..510789e0 100644 --- a/docs/master/introduction/providers.md +++ b/docs/master/introduction/providers.md @@ -7,11 +7,11 @@ indent: true # Providers -Providers extend Crossplane to enable infrastructure resource provisioning. -In order to provision a resource, a Custom Resource Definition(CRD) -needs to be registered in your Kubernetes cluster and its controller should -be watching the Custom Resources those CRDs define. Provider packages -contain many Custom Resource Definitions and their controllers. +Providers extend Crossplane to enable infrastructure resource provisioning. In +order to provision a resource, a Custom Resource Definition (CRD) needs to be +registered in your Kubernetes cluster and its controller should be watching the +Custom Resources those CRDs define. Provider packages contain many Custom +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 - install the default version hard-coded in that release of Crossplane Helm - chart but if you'd like to specif an exact version, you can add: `--set - clusterPackages.gcp.version=master`. -* Using [Crossplane kubectl plugin][crossplane-cli]: `kubectl crossplane package - install --cluster -n crossplane-system 'crossplane/provider-gcp:master' - provider-gcp` + `helm install` command: `--set + provider.packages={crossplane/provider-aws:master}`. +* Using the Crossplane CLI: `kubectl crossplane install provider + crossplane/provider-aws:master` 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