Crossplane manages Resources external via Providers. Providers are composed of Kubernetes Custom Resource Definitions and Controllers that communicate to a remote API and manages the lifecycle of a resource from Creation to Deletion.
To build a new provider, please refer to the Provider Development Guide.
This document contains list of items that are usually involved in managing Open Source contributions to a Crossplane provider. In general your provider should follow the guidelines documented in the Crossplane Contributing guide.
Although providers can be hosted in any source code repository, the crossplane-contrib Github Organization is available as a neutral home that is under Crossplane's project governance.
Members of the Crossplane community are happy to create a repository in the crossplane-contrib organization and configure access, continuous integration, and storage for software artifacts. Please open an issue in the Crossplane org repository or reach out to the Crossplane #dev channel.
Generally projects are named provider-<name>, with name being the API being
managed. Example project names are provider-aws, provider-kubernetes,
and provider-github.
The provider-cmdb repository can be used as a starting point for new providers. For terrajet-based providers, the provider-jet-template is available.
Most Crossplane providers include the following files:
- A descriptive README.md at the root of the project (see provider-gcp/README.md as an example)
- Code is licensed under the Apache 2.0 License
- Include a “Developer Certificate of Origin”. Example: DCO
- Include the CNCF Code of Conduct
- Update OWNERS.md with contacts for project Owners
- Ensure
hack/boilerplate.go.txt(used in Code generation) includes Crossplane Authors, Apache license and any other Copyright statements: https://github.com/crossplane/provider-cmdb/blob/main/hack/boilerplate.go.txt - Include Documentation on how to:
- Install Provider
- Contribute to Development
- Authenticate to backend API, including creating Kubernetes secrets for the ProviderConfig
- Include examples for the ProviderConfig and each resource in the
examples/directory.
There are a number of build tools and processes that are common across the Crossplane ecosystem. Using these ensures a consistent development environment across projects.
The provider-cmdb repository contains most of these settings.
- Use the Upbound build submodule. (see https://github.com/crossplane/crossplane/blob/master/CONTRIBUTING.md#establishing-a-development-environment)
- Include a Makefile that supports common build targets.
- Use a Golang linter. Example: https://github.com/crossplane/provider-aws/blob/master/.golangci.yml
- Create a Crossplane Package configuration (see package/crossplane.yaml)
When deploying provider artifacts, projects should generally follow the Crossplane release process.
Most Crossplane projects use Github Actions to build, tag, and promote software releases.
Providers are packaged as OCI (Docker) images and pushed to an OCI registry as part of the publish and promotion workflows.
In general, providers should:
- Utilize GitHub workflows from https://github.com/crossplane/provider-cmdb/tree/main/.github/workflows
- Create OCI image repos to push Package and Controller images.
- Automatically push Provider images and packages via CI
- Add GitHub Secrets to push to Docker repository. (To be performed by Crossplane-contrib administrators).
If you're part of the crossplane-contrib org and want to enable Github CI, push OCI images or packages to the crossplane org in Docker Hub please ask a steering committee member to grant your project access to the GitHub org scoped secrets.
- Follow recommendations at https://github.com/crossplane/crossplane/blob/master/GOVERNANCE.md#repository-governance
- Enable Issues on your project and configure Issue templates (examples at: .github/ISSUE_TEMPLATE)
- Create Pull Request Templates: (example: PULL_REQUEST_TEMPLATE.md)