Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewrite packages content and split into Config and Provider chapters #566

Merged
merged 14 commits into from
Oct 31, 2023
Merged
82 changes: 0 additions & 82 deletions content/knowledge-base/guides/troubleshoot.md
Original file line number Diff line number Diff line change
Expand Up @@ -387,88 +387,6 @@ For example, for a `CloudSQLInstance` managed resource (`database.gcp.crossplane
kubectl patch cloudsqlinstance my-db -p '{"metadata":{"finalizers": []}}' --type=merge
```

## Installing Crossplane Package

After installing [Crossplane package], to verify the install results or
troubleshoot any issue spotted during the installation, there are a few things
you can do.

Run below command to list all Crossplane resources available on your cluster:

```shell
kubectl get crossplane
```

If you installed a Provider package, pay attention to the `Provider` and
`ProviderRevision` resource. Especially the `INSTALLED` and `HEALTHY` column.
They all need to be `TRUE`. Otherwise, there must be some errors that occurred
during the installation.

If you installed a Configuration package, pay attention to the `Configuration`
and `ConfigurationRevision` resource. Again, the `INSTALLED` and `HEALTHY`
column for these resources need to be `TRUE`. Besides that, you should also see
the `CompositeResourceDefinition` and `Composition` resources included in this
package are listed if the package is installed successfully.

If you only care about the installed packages, you can also run below command
which will show you all installed Configuration and Provider packages:

```shell
kubectl get pkg
```

When there are errors, you can run below command to check detailed information
for the packages that are getting installed.

```shell
kubectl get lock -o yaml
```

To inspect a particular package for troubleshooting, you can run
`kubectl describe` against the corresponding resources, e.g. the `Provider` and
`ProviderRevision` resource for Provider package, or the `Configuration` and
`ConfigurationRevision` resource for Configuration package. Usually, you should
be able to know the error reason by checking the `Status` and `Events` field for
these resources.

## Handling Crossplane Package Dependency

When using `crossplane.yaml` to define a Crossplane Configuration package, you
can specify packages that it depends on by including `spec.dependsOn`. You can
also specify version constraints for dependency packages.

When you define a dependency package, please make sure you provide the fully
qualified address to the dependency package, but do not append the package
version (i.e. the OCI image tag) after the package name. This may lead to the
missing dependency error when Crossplane tries to install the dependency.

When specifying the version constraint, you should strictly follow the
[semver spec]. Otherwise, it may not be able to find the appropriate version for
the dependency package even it says the dependency is found. This may lead to an
incompatible dependency error during the installation.

Below is an example where a Configuration package depends on a provider pulled
from `xpkg.upbound.io/crossplane-contrib/provider-aws`. It defines `">=v0.18.2`
as the version constraint which means all versions after `v0.16.0` including all
prerelease versions, in the form of `-xyz` after the normal version string, will
be considered when Crossplane tries to find the best match.

```yaml
apiVersion: meta.pkg.crossplane.io/v1
kind: Configuration
metadata:
name: test-configuration
annotations:
provider: aws
spec:
crossplane:
version: ">=v1.4.0-0"
dependsOn:
- provider: xpkg.upbound.io/crossplane-contrib/provider-aws
version: ">=v0.18.2"
```


## Tips, Tricks, and Troubleshooting

In this section we'll cover some common tips, tricks, and troubleshooting steps
Expand Down
Loading
Loading