Here's the one-liner to install latest released version:
curl -sL https://raw.githubusercontent.com/crossplaneio/crossplane-cli/master/bootstrap.sh | bash
The behavior is customizable via environment variables:
RELEASE=v0.2.0
PREFIX=${HOME}
curl -sL https://raw.githubusercontent.com/crossplaneio/crossplane-cli/"${RELEASE}"/bootstrap.sh | env PREFIX=${PREFIX} RELEASE=${RELEASE} bash
You can get the latest, bleeding-edge versions of the stack commands
by setting RELEASE as master.
RELEASE=master && curl -sL https://raw.githubusercontent.com/crossplaneio/crossplane-cli/"${RELEASE}"/bootstrap.sh | RELEASE=${RELEASE} bash
But please note, the trace command will not be installed in this case,
because it's a built binary and isn't set up to be easily downloaded
from master. To use trace from master, we recommend building and
installing from source.
If you have the source repository checked out, installing is simple as
long as you have golang installed:
make build
make install
If you followed the installation process above, you can remove everything with:
rm /usr/local/bin/kubectl-crossplane-*
Or, if you customized the installation prefix:
PREFIX=/thing
rm "${PREFIX}"/bin/kubectl-crossplane-stack-*
If you have the source repository checked out:
make uninstall
kubectl crossplane stack init 'myname/mysubname'
kubectl crossplane stack build
kubectl crossplane stack publish
kubectl crossplane stack install 'myname/mysubname'
kubectl crossplane stack generate-install 'myname/mysubname' | kubectl apply --namespace mynamespace -f -
kubectl crossplane stack list
kubectl crossplane stack uninstall 'myname-mysubname'
Trace command aims to ease debugging and troubleshooting process by providing a holistic view for a particular object. It finds the relevant objects for a given one and provides detailed information.
kubectl crossplane trace TYPE[.GROUP] NAME [-n| --namespace NAMESPACE]
Examples:
# Trace a KubernetesApplication
kubectl crossplane trace KubernetesApplication wordpress-app-83f04457-0b1b-4532-9691-f55cf6c0da6e -n app-project1-dev
# Trace a MySQLInstance
kubectl crossplane trace MySQLInstance wordpress-mysql-83f04457-0b1b-4532-9691-f55cf6c0da6e -n app-project1-dev
# Graph output, which can be visualized with graphviz as follows.
kubectl crossplane trace KubernetesApplication wordpress-app-83f04457-0b1b-4532-9691-f55cf6c0da6e -n app-project1-dev -o dot | dot -Tpng > /tmp/output.png
For more information, see the trace command documentation.
This guide will show you the basics for using the Stacks CLI to create and develop a stack with a basic controller that responds to a certain type of object.
This guide uses kubebuilder version 2, but other approaches can be used too.
Excluding installing prerequisites, it'll take about 5 minutes!
The workflow for working with a stack assumes that you have a few things installed:
- go
- docker
- kubectl
- kubebuilder, version 2
- GNU make
- bash
- crossplane,
or your
kubectlshould be set up to talk to a crossplane control cluster
make and bash are probably already installed if you're using a
Unix-like environment or MacOS.
Instructions to install kubebuilder come from the kubebuilder quick start, but are reproduced here for convenience.
os=$(go env GOOS)
arch=$(go env GOARCH)
# download kubebuilder and extract it to tmp
curl -sL https://go.kubebuilder.io/dl/2.0.0/${os}/${arch} | tar -xz -C /tmp/
# move to a long-term location and put it on your path
# (you'll need to set the KUBEBUILDER_ASSETS env var if you put it somewhere else)
sudo mv /tmp/kubebuilder_2.0.0_${os}_${arch} /usr/local/kubebuilder
export PATH=$PATH:/usr/local/kubebuilder/bin
Installing the kubectl plugins is pretty simple.
Copy the plugins to somewhere on your PATH. If you have
/usr/local/bin on your PATH, you can do it like this:
RELEASE=master && curl -sL https://raw.githubusercontent.com/crossplaneio/crossplane-cli/"${RELEASE}"/bootstrap.sh | RELEASE=${RELEASE} bash
First you'll need a folder to work with. Initializing it probably looks something like the following:
mkdir helloworld
cd helloworld
git init
Once the project is initialized, we'll set it up as a kubebuilder project.
If your project is within the GOPATH, you can do:
GO111MODULE=on kubebuilder init --domain helloworld.stacks.crossplane.io
If your project is not within the GOPATH, you need to do an extra step first. See the
kubebuilder quick start guide for more details.
The instructions in this guide will use GO111MODULE=on in front of all
of the kubebuilder commands, but it could also be set once at the
beginning with export GO111MODULE=on, or set in other ways.
Next, create an API using kubebuilder:
yes y | GO111MODULE=on kubebuilder create api --group samples --version v1alpha1 --kind HelloWorld
Once the project is initialized as a kubebuilder project and the plugins
are installed, we can initialize the project as a stack project using
the crossplane stack init command.
From within the project directory:
kubectl crossplane stack init --cluster 'crossplane-examples/hello-world'
Now we'll add some custom functionality to our controller.
Add a "Hello World" log line to the kubebuilder controller, which should
be in the controllers/ directory:
// your logic here
r.Log.V(0).Info("Hello World!", "instance", req.NamespacedName)
First, we'll want to build the binaries and yamls in the regular way.
GO111MODULE=on make manager manifests
During development, we'll often be building and testing our stack locally. The local validation section shows us how we would do that.
These local scenarios will attempt to run a local Docker registry in your Kubernetes cluster to help with publishing your Stack image for local testing scenarios. This local validation flow has been tested and verified with the following software:
- Docker Desktop
2.2.0.0with Kubernetesv1.15.5enabled - Crossplane
v0.7.0installed into Docker Desktop's Kubernetes cluster
Once the (kubebuilder) project is built in the normal way, we want to bundle it all into a stack and publish the image locally:
kubectl crossplane stack build local-build
When the stack is built, the next step is to install it into our Crossplane:
kubectl crossplane stack install --cluster 'crossplane-examples/hello-world' 'crossplane-examples-hello-world' localhost:5000
This can also be done using the sample local stack install that the
init command generates, but it's a good habit to use the install
command.
Once the stack is installed into our Crossplane, we can use one of the sample objects to create an object that the stack will respond to.
kubectl apply -f config/samples/*.yaml
Once the object has been created, we expect the controller to do something in response! In our case, we expect it to log a message.
We can check whether the controller is running and logging messages
using a kubectl get to identify the pod running the controller,
followed by a kubectl logs to read the logs of that pod:
$ kubectl get pods -A | grep hello-world | grep -v Completed
default crossplane-examples-hello-world-65d5c59976-vzppd 1/1 Running 0 91s
$ kubectl logs crossplane-examples-hello-world-65d5c59976-vzppd | grep 'Hello World'
2019-08-28T23:37:51.795Z INFO controllers.HelloWorld Hello World! {"instance": "default/helloworld-sample"}
That's it! We've finished writing, building, and locally validating a stack!
When we're done with the stack and want to remove it and all its
resources, we can uninstall it by name:
kubectl crossplane stack uninstall --cluster 'crossplane-examples-hello-world'
After we finish developing a stack locally, we may want to publish it to an external registry. This section shows the commands to do that.
To build the stack, we use the build subcommand once the binaries and
generated yamls have been built:
kubectl crossplane stack build
Once the stack is built, we can use the publish subcommand to publish
it to the registry:
# You may need to log into dockerhub or the docker registry that the
# image is being pushed to. If that's the case, run:
# $ docker login
kubectl crossplane stack publish
Installing the stack can be done with a sample which was generated for
us by the init that we ran earlier, but it's a little easier to use
the install command:
kubectl crossplane stack install --cluster 'crossplane-examples/hello-world'
Installing the stack can be done with some sample yaml which was
generated for us by the init that we ran earlier, but it's a
little easier to use the uninstall command:
kubectl crossplane stack uninstall --cluster 'crossplane-examples-hello-world'
Note that uninstall uses the stack's name (which has no / characters),
while the install uses the image name (which uses /).
STACK_IMG=myprefix/myothername kubectl crossplane stack build
STACK_IMG=myprefix/myothername kubectl crossplane stack publish
We can specify a different build target to run:
kubectl crossplane stack build local-build
See the config/stack/overrides directory for details about where the
overrides live. See the stack.Makefile for details about how
local-build works.
We can setup extra permissions to grant access to the resources which are not part of our stack. This can be done by specifying the permissions in the stack definition YAML..
# Human readable title of application.
title: Sample Wordpress Stack
...
# RBAC Roles will be generated permitting this stack to use all verbs on all
# resources in the groups listed below.
permissionScope: Namespaced
dependsOn:
- crd: "kubernetesclusters.compute.crossplane.io/v1alpha1"
- crd: "mysqlinstances.database.crossplane.io/v1alpha1"
- crd: "kubernetesapplications.workload.crossplane.io/v1alpha1"
...
For a detailed example, check this