crossplane / crossplane-cli

Tools and commands for managing and developing Crossplane

Crossplane is a framework for building cloud native control planes without needing to write code. It has a highly extensible backend that enables you to build a control plane that can orchestrate applications and infrastructure no matter where they run, and a highly configurable frontend that puts you in control of the schema of the declarative API it offers.

Crossplane is a Cloud Native Computing Foundation project.

Get Started

Crossplane's Get Started Docs cover install and cloud provider quickstarts.

Releases

Currently maintained releases, as well as the next few upcoming releases are listed below. For more information take a look at the Crossplane release cycle documentation.

Release	Release Date	EOL
v1.14	Nov 1, 2023	Aug 2024
v1.15	Feb 15, 2024	Nov 2024
v1.16	May 15, 2024	Feb 2025
v1.17	Early Aug '24	May 2025
v1.18	Early Nov '24	Aug 2025
v1.19	Early Feb '25	Nov 2025

You can subscribe to the community calendar to track all release dates, and find the most recent releases on the releases page.

Roadmap

The public roadmap for Crossplane is published as a GitHub project board. Issues added to the roadmap have been triaged and identified as valuable to the community, and therefore a priority for the project that we expect to invest in.

The maintainer team regularly triages requests from the community to identify features and issues of suitable scope and impact to include in this roadmap. The community is encouraged to show their support for potential roadmap issues by adding a 👍 reaction, leaving descriptive comments, and attending the regular community meetings to discuss their requirements and use cases.

The maintainer team updates the roadmap on an as needed basis, in response to demand, priority, and available resources. The public roadmap can be updated at any time.

Milestones assigned to any issues in the roadmap are intended to give a sense of overall priority and the expected order of delivery. They should be considered approximate estimations and are not a strict commitment to a specific delivery timeline.

Crossplane Roadmap

Get Involved

Crossplane is a community driven project; we welcome your contribution. To file a bug, suggest an improvement, or request a new feature please open an issue against Crossplane or the relevant provider. Refer to our contributing guide for more information on how you can help.

• Discuss Crossplane on Slack or our developer mailing list.
• Follow us on Twitter or LinkedIn, or subscribe to our newsletter.
• Contact us via Email.
• Join our regular community meetings.
• Provide feedback on our roadmap and releases board.

The Crossplane community meeting takes place every 4 weeks on Thursday at 10:00am Pacific Time. You can find the up to date meeting schedule on the Community Calendar.

Anyone who wants to discuss the direction of the project, design and implementation reviews, or raise general questions with the broader community is encouraged to join.

• Meeting link: https://zoom.us/j/425148449?pwd=NEk4N0tHWGpEazhuam1yR28yWHY5QT09
• Current agenda and past meeting notes
• Past meeting recordings
• Community Calendar

Special Interest Groups (SIG)

Each SIG collaborates in Slack and some groups have regular meetings, you can find the meetings in the Community Calendar.

• #sig-composition-environments
• #sig-composition-functions
• #sig-deletion-ordering
• #sig-devex
• #sig-docs
• #sig-e2e-testing
• #sig-observability
• #sig-observe-only
• #sig-provider-families
• #sig-secret-stores
• #sig-upjet

Adopters

A list of publicly known users of the Crossplane project can be found in ADOPTERS.md. We encourage all users of Crossplane to add themselves to this list - we want to see the community's growing success!

License

Crossplane is under the Apache 2.0 license.

crossplane-cli's Issues

Support tracing cluster-scoped resources like GCPSample stack instances, so I can see progress

Build and publish: simplified CLI UX

What seems to be the problem

To build and publish a stack the following steps are required:

1. Run the following commands:

$ git clone [email protected]:crossplaneio/stack-minimal-gcp.git

$ cd stack-minimal-gcp

$ kubectl crossplane stack build

$ docker tag crossplane/stack-minimal-gcp crossplane/stack-minimal-gcp:v0.2.2

$ docker login registry.dev
Username: [email protected]
Password:

$ kubectl crossplane stack publish registry.dev/crossplane/stack-minimal-gcp

What could we do to help?

Support a cleaner build and publish CLI UX that does all the steps above:

VERSION=0.0.1
kubectl crossplane registry login registry.dev
kubectl crossplane stack build registry.dev/crossplane/stack-minimal-gcp:${VERSION}
kubectl crossplane stack publish registry.dev/crossplane/stack-minimal-gcp:${VERSION}

Support Command Autocompletion

The cli should support autocompletion for better usability and command discovery.

Add "crossplane create" for crossplane claim and class types

What is the problem you are facing?

"kubectl create" includes the ability to create specific resource types using a simple interface with command line arguments that populate the spec of the created resources, in some cases with data conversion. This simplifies the user experience.

kubectl create can not be extended to understand new types and the crossplane-cli does not offer this experience.

How can Crossplane improve this?

"kubectl crossplane" should include a "create" command that can perform a similar role for Crossplane's claim and class types. For the core types the CLI can include help describing the parameters available, and any data format or content conversions that the CLI performs.

If this is implemented dynamically (generically), for "crossplane create" types, structured spec data may be harder to support. We would not have helper conversion functions available for these parameters.

Dynamic documentation may be adapted from kubectl explain facilities which is drawn from the CRD itself. An approach to list all CRDs owned by Stacks would be needed.

One benefit of a dynamic approach is that this command could easily provide a create command for all managed resource, claim, and class types for all installed stacks.

One (static) approach would be to create scripts such as "kubectl-crossplane-create-mysqlinstance" for each type.

This approach would keep the code easy to review, allow for different implementations (languages) per resource, and would suggest that stack authors may provide similar plugins for their stack resource types.

Stack Install should take a namespace option

Documentation currently advises using:

kubectl crossplane stack generate-install image name source | kubectl -n namespace apply -f -

The UX on installs could be improved with a -n argument to install:

kubectl crossplane stack install -n namespace image name source

trace should include serviceaccount and role listings

Tracing a resource could have options (--serviceaccount, --roles) to reveal the ServiceAccount and the subordinate Role records granted to a resource's Stack's deployment.

This would allow users to identify the associated roles, which could also aid in detection of missing roles.

I'm open to rebuttals that this may be more of an inventory feature than a tracing feature.

support --imagePullSecret=<name> option for kubectl crossplane package install

Problem

Would like to install packages from a private repo using kubectl crossplane package install e.g. with a --imagePullSecret <name> option that references a standard image pull secret created with a separate command.

what could we do to help?

Support the following flow:
kubectl create secret docker-registry package-pull-secret --docker-username=<username> --docker-password=<password> --namespace=<ns>

kubectl crossplane package install --namespace <ns> <package> <name> <registry> --imagePullSecret=<name>

Add crossplane-cli to krew-index

In order to make Crossplane CLI more discoverable and easier to install/upgrade, it should be made available in the Krew Index: https://github.com/kubernetes-sigs/krew-index

Requirements of adding Crossplane CLI to krew include:

• adding the LICENSE file to the release tarball
• creating a PR on krew-index abiding by the publishing guidelines: https://github.com/kubernetes-sigs/krew/blob/master/docs/DEVELOPER_GUIDE.md#publishing-plugins
• adding a kubectl-crossplane-krew wrapper to serve as a single point of entry for a single crossplane plugin (to prevent the need to make a new plugin entry for each subcommand)

Paraphrasing @ahmetb:

Krew doesn't support shipping all of the separate plugins at once.
So the recommendation is to:

• create a single entrypoint like kubectl-crossplane-krew
• have this script discover its installation directory (eg $(dirname $(readlink "$0")))
• based on args, it would call $dir/kubectl-crossplane-XXX

The entrypoint bin would be kubectl-crossplane-krew, and so long as the plugin is named crossplane, it will be linked as kubectl-crossplane. Refer to https://github.com/kubernetes-sigs/krew/blob/master/docs/DEVELOPER_GUIDE.md#installing-plugins-locally for local development.

package publish should not try publishing to separate amd64/arm64 repositories

kubectl crossplane package publish requires three repositories to exist, for example:

• foo
• foo-amd64
• foo-arm64

This creates an operational burden on the developer and host. It would be preferable to offer a way to publish to the base repository without requiring the architecture suffix repos.

I believe the problem stems from https://github.com/upbound/build/blob/master/makelib/image.mk#L189-L203, but I am filing the issue here since this solution shouldn't have to depend on upbound/build changes.

Publish new release of crossplane-cli

The current deployed version of crossplane-cli:
curl -sL https://raw.githubusercontent.com/crossplaneio/crossplane-cli/master/bootstrap.sh | bash

does not include needed info such as namespace when installing a stack. Therefore, installing stacks via the command line does not work on this version.

In order for stack installs to work with specifying a namespace, we need to update to release a new version that has all the functionality currently in master.

package init should offer tempate stack options to init from helm3 or kustomize

What is the problem?

The current package init command expects to be invoked from a kubebuilder project.

Tempate stacks can be created with only helm3 or kustomize files.

What does it look like when it's done?

The init command should offer arguments to simplify the experience when working in this environment.

Should this be the default mode? Should the environment be detected (and overridable)?

update command names to use "package" instead of "stack" per updated terminology

kubectl crossplane package uninstall: gets stuck for 30 seconds and returns error

Problem

kubectl crossplane package uninstall gets stuck for 30 seconds, but the package is successfully deleted.

Using:

• Crossplane CLI master
• Wordpress v0.3.0
• AWS Provider v0.8.0
• AWS Sample Stack v0.4.0
• Crossplane 0.10.0-rc.113.ga1d1fa1

RELEASE=master && curl -sL https://raw.githubusercontent.com/crossplane/crossplane-cli/"${RELEASE}"/bootstrap.sh | RELEASE=${RELEASE} bash

kubectl crossplane package install --namespace ws1 crossplane/app-wordpress:v0.3.0 app-wordpress <registry>

kubectl crossplane package uninstall --namespace ws1 app-wordpress

stackinstall.stacks.crossplane.io "app-wordpress" deleted

Error from server (InternalError): an error on the server ("<html><head>\n<meta http-equiv=\"content-type\" content=\"text/html;charset=utf-8\">\n<title>502 Server Error</title>\n</head>\n<body text=#000000 bgcolor=#ffffff>\n<h1>Error: Server Error</h1>\n<h2>The server encountered a temporary error and could not complete your request.<p>Please try again in 30 seconds.</h2>\n<h2></h2>\n</body></html>") has prevented the request from succeeding

Additional repro steps:

RELEASE=master && curl -sL https://raw.githubusercontent.com/crossplane/crossplane-cli/"${RELEASE}"/bootstrap.sh | RELEASE=${RELEASE} bash

kubectl crossplane package install --cluster --namespace crossplane-system crossplane/provider-aws:v0.8.0 provider-aws <registry>

kubectl crossplane package uninstall --cluster --namespace crossplane-system provider-aws

clusterstackinstall.stacks.crossplane.io "provider-aws" deleted

Error from server (InternalError): an error on the server ("<html><head>\n<meta http-equiv=\"content-type\" content=\"text/html;charset=utf-8\">\n<title>502 Server Error</title>\n</head>\n<body text=#000000 bgcolor=#ffffff>\n<h1>Error: Server Error</h1>\n<h2>The server encountered a temporary error and could not complete your request.<p>Please try again in 30 seconds.</h2>\n<h2></h2>\n</body></html>") has prevented the request from succeeding

stack install fails for stacks with an image tag

STACK_NAME appears to be optional in the stack install help. This is reasonable as a default STACK_NAME could be derived from the image name presented in the STACK_IMAGE_NAME (org/name:version).

$ kubectl crossplane stack install --help
Usage: kubectl crossplane stack install [-h|--help] [-c|--cluster] STACK_IMAGE_NAME [STACK_NAME [STACK_IMAGE_SOURCE]]
...

However, STACK_NAME appears to be required when using real-world images. I can see how local image names would not contain slashes ("/") and could potentially omit a version, so STACK_NAME may technically be optional today in some limited cases.

$ kubectl crossplane stack install --cluster crossplane/stack-gcp:v0.2.0
The ClusterStackInstall "crossplane-stack-gcp:v0.2.0" is invalid: metadata.name: Invalid value: "crossplane-stack-gcp:v0.2.0": a DNS-1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')

Show the version of Crossplane and given stack

Currently, the way to check the version of Crossplane or a provider is:

kubectl get -n <namespace> deploy crossplane -o yaml | grep image:
kubectl get -n <namespace> deploy provider-aws-controller -o yaml | grep image:

This requires user to know the deployment name of the stack. A kubectl style information would've been nicer for Crossplane:

kubectl version
Client Version: version.Info{Major:"1", Minor:"17", GitVersion:"v1.17.3", GitCommit:"06ad960bfd03b39c8310aaf92d1e7c12ce618213", GitTreeState:"clean", BuildDate:"2020-02-13T18:08:14Z", GoVersion:"go1.13.8", Compiler:"gc", Platform:"darwin/amd64"}
Server Version: version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.2", GitCommit:"f6278300bebbb750328ac16ee6dd3aa7d3549568", GitTreeState:"clean", BuildDate:"2019-08-05T09:15:22Z", GoVersion:"go1.12.5", Compiler:"gc", Platform:"linux/amd64"}

And for stacks something like:

crossplane stacks --name provider-aws version

Support namespace for stack installations

Currently, kubectl crossplane stack install works for default and only default namespace. People who need to deploy the stack into a different namespace have to go with kubectl crossplane stack install ... | kubectl -n myns -f -.

It'd be good if crossplane cli supported namespaces natively.

local docker registry: name filter should be more exact

I was running the local-build build for a stack locally, and I realized that multiple containers match the name=registry filter.

When I used docker ps --filter name='^registry$' as the name filter instead, only the one with the actual full name registry came back.

We should update the filter to use the more precise match.

Support provider plugins

Crossplane handles much of the operations to adopt existing infrastructure and begin managing it. However, it cannot determine what resources a user wants to adopt from their provider without fairly significant manual intervention by the user in some cases. It would be nice for the libraries used in providers to also be able to be used to generate CRs for existing infrastructure types. I imagine the experience looking something like this:

1. crossplane-cli provides extension points for plugins to be installed. Maybe they are installed automatically if you use the CLI to install the provider into your cluster (see using labels on CRDs below).
2. The provider plugins satisfy interfaces for getting resources from the provider via simple CLI commands.
3. A user may list existing infrastructure using the CLI, then choose resources they wish to be rendered and applied as CRs for Crossplane to gain control of.

Much of this effort for providers would just be re-purposing existing code and supplying the appropriate endpoints. In fact, it may be possible to handle this as labels on the CRDs. For instance, a CRD for CloudSQL could include a label like get.cli.crossplane.io/endpoint: https://www.googleapis.com/sql/v1beta4/projects/{project}/instances.

Add ability to add kubeconfig from KubernetesCluster resource

Now that we include the raw kubeconfig in kubernetes cluster connection secrets (crossplane/crossplane#861 thanks @muvaf!), it would be nice to have a single command as part of the CLI that allows merging the kubeconfig in the secret with the local kubeconfig such that users can easily connect directly to the remote cluster.

Build and publish: better configurability

What is the problem?

Currently, the build and publish commands look for a stack.Makefile in the stack which is affected. This was originally created so that stack build logic would play nicely with kubebuilder-based scaffolding with minimal modification.

However, now that we have template stacks, it's a bit inconvenient to have a thin Makefile and a stack.Makefile, and it seems redundant.

What does this look like when it's done?

We would support running the build and publish commands with controller-based stacks and template stacks, without it feeling clunky. Because we expect template stacks to be more common than controller-based stacks, it should be okay to optimize for the template case a little bit.

The template case will likely have a single Makefile, so one way to do this would be to use stack.Makefile if it exists, but to use the Makefile if stack.Makefile does not exist. These would be changes in the build and publish commands.

Import Existing Resources

The Issue

The process of importing existing resources from a provider into a crossplane resource is quite tedious and a bit dangerous. The crossplane resource must match exactly all the properties to the existing resource from the provider. If the props don't exactly match; the resource will be modified to match what the crossplane resource says. If one were to accidentally omit a property then that property will be removed and/or set to its default instead of what it should be.

here are the docs on importing, which in my opinion are a little lite on the specifics: Crossplane Import Existing Resources

Suggested Solution

Would be nice to have the Crossplane CLI make the imported resource yaml for me.

I imagine a command like:
kubectl crossplane import aws vpc MyCoolVPC

The command would take a few different kinds of params like name, id, or ARN.
kubectl crossplane import aws vpc vpc-123abc456def

Then the generated output would be something like:

apiVersion: network.aws.crossplane.io/v1alpha3
kind: VPC
metadata:
  name: my-cool-vpc
  annotations:
    crossplane.io/external-name: vpc-someid
spec:
  cidrBlock: 10.100.0.0/16
  enableDnsHostNames: true
  enableDnsSupport: true
  reclaimPolicy: Retain
  tags:
    Name: MyCoolVPC
    "aws:cloudformation:logical-id": VPCA1B23C
    "aws:cloudformation:stack-id": "arn:aws:cloudformation:us-west-2:1234567:stack/MyStack/8f834j340"
    "aws:cloudformation:stack-name": MyStack
  providerRef:
    name: aws-provider

In the example above, if I were to forget to add the tags made by cloudformation, then the resource would get disassociated from the cloudformation stack and bad things would happen. Even worse, what if the cidrBlock was typed in wrong. . . Importing from the CLI would prevent a person from any dumb human mistakes.

trace utility UX enhancements

What seems to be the problem

Would like enhanced UX for the trace utility in the following areas:

• Improve overview of text output to represent the hierarchy

• Support tracing resources referenced with
  cross resource referencing.

• Support dynamically defining new resources/relations (via a config file) without rebuilding the binary which can
  position the tool as a general purpose tracing tool for tracing any Kubernetes Resource. This could make supporting
  cross resource referencing
  much easier.

• Based on the pattern established for parent child relationships,
  support tracing starting with stack instances.

See also:

• https://github.com/crossplaneio/crossplane-cli/blob/master/docs/trace-command.md#future-work

stack init should set up per resource metadata

Crossplane stacks support metadata and icons for every resource (CRD) defined in the stack, such as:

• resource.yaml
• icon.svg
• ui-schema.yaml

For example, this PR is adding icons and metadata for each CRD in the GCP stack:
crossplane-contrib/provider-gcp#28

stack init should set up the scaffolding to support per resource metadata, so that stack builds will automatically include/package them in the appropriate layout.

Consider adding crossdocs functionality to crossplane-cli

Currently, the API docs on crossplane.io are generated using crossdocs. However, this is a cumbersome process that makes it difficult for new contributors to regenerate API docs when they make changes that affect them. It is also not obvious or documented that the tool is how we generate our API docs, nor is it obvious when API docs need to be regenerated (addressed by crossplane/crossplane#1166). Furthermore, there are a number of issues with crossdocs currently that cause broken links and poorly formatted documentation (ref: crossplane/crossplane#1223).

Moving the crossdocs functionality to crossplane-cli is advantageous for the following reasons:

• Helps movement toward doing all code generation and crossplane operations with a single tool
• Adding generation to crossplane-cli is an opportunity for rewrite and fixing of existing bugs
• Makes it easier for stacks built outside of the crossplaneio org to have good documentation with minimal effort

Consider migrating bash scripts to Go

Currently all of crossplane-cli is written in bash except for the trace command. In order to make the code more testable, easier to modify, and able to compiled into a single binary, it would be useful to migrate the existing bash scripts to Go.

`kubectl crossplane` should show help and subcommands

Users will be confused when kubectl crossplane returns an error.

The bin directory should include a kubectl-crossplane and kubectl-crossplane-stack to list the available subcommands.