Documentation

Stacks Guide

Table of Contents

  1. Introduction
  2. Concepts
  3. Before you get started
  4. Install the Crossplane CLI
  5. Install and configure Crossplane
  6. Install support for our application into Crossplane
  7. Create a Wordpress
  8. Clean up
  9. Conclusion
  10. Next steps
  11. References

Introduction

Welcome to the Crossplane Stack guide! In this document, we will:

We will not:

Let’s go!

Concepts

There are a bunch of things you might want to know to fully understand what’s happening in this document. This guide won’t cover them, but there are other ones that do. Here are some links!

Before you get started

This guide assumes you are using a *nix-like environment. It also assumes you have a basic working familiarity with the following:

You will need:

Install the Crossplane CLI

To interact with stacks, we’re going to use the Crossplane CLI, because it’s more convenient. To install it, we can use the one-line curl bash:

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

To use the latest release, you can use master as the RELEASE instead of using a specific version.

Install and configure Crossplane

To use Crossplane, we’ll need to install and configure it. In this case, we want to use Crossplane with a cloud provider, so we’ll need to configure the provider.

Install Crossplane

The recommended way of installing Crossplane is by using helm. We can grab the most stable version currently available by using:

helm repo add crossplane-alpha https://charts.crossplane.io/alpha
helm install --name crossplane --namespace crossplane-system crossplane-alpha/crossplane

For more options for installing, including how to install a more bleeding-edge version, or how to uninstall, see the full install documentation.

Create the application namespace

Kubernetes namespaces are used to isolate resources in the same cluster, and we’ll use them in our Crossplane control cluster too. Let’s create a namespace for our application’s resources. We’ll call it app-project1-dev for the purposes of this guide, but any name can be used.

kubectl create namespace app-project1-dev

The reason we need to create the namespace before we configure the cloud provider is because we will be setting up some cloud provider configuration in that namespace. The configuration will help our application not care about which specific provider it uses. For more details on how this works, see the Crossplane documentation on portable classes.

Configure support for your cloud provider

Next we’ll set up support for our cloud provider of choice! See the provider-specific guides:

Then come back here! Don’t worry; we’ll still be here when you’re ready.

Don’t see your favorite cloud provider? Help us add support for it!

Install support for our application into Crossplane

Now that we’ve got Crossplane set up and configured to use a cloud provider, we’re ready to add support for creating WordPresses! We’ll do this using a Crossplane Stack. For more information about stacks, see the full Stack documentation.

We can use the Crossplane CLI to install our stack which adds support for Wordpress. Let’s install it into a namespace for our project, which we’ll call app-project1-dev for the purposes of this guide. To install to the current namespace, install can be used, but since we want to install to a specific namespace, we will use generate-install:

kubectl crossplane stack generate-install 'crossplane/sample-stack-wordpress:latest' 'sample-stack-wordpress' | kubectl apply --namespace app-project1-dev -f -

Using the generate-install command and piping the output to kubectl apply instead of using the install command gives us more control over how the stack’s installation is handled. Everything is a Kubernetes object!

This pulls the stack package from a registry to install it into Crossplane. For more details about how to use the CLI, see the documentation for the CLI. For more details about how stacks work behind the scenes, see the documentation about the stack manager and the stack format.

Create a Wordpress

Now that Crossplane supports Wordpress creation, we can ask Crossplane to spin up a Wordpress for us. We can do this by creating a Kubernetes resource that our Wordpress stack will recognize:

cat > my-wordpress.yaml <<EOF
apiVersion: wordpress.samples.stacks.crossplane.io/v1alpha1
kind: WordpressInstance
metadata:
  name: my-wordpressinstance
EOF

kubectl apply --namespace app-project1-dev -f my-wordpress.yaml

To validate that it has been set up correctly, we can run:

kubectl -n app-project1-dev get stack

The output should look something like:

NAME                     READY   VERSION   AGE
sample-stack-wordpress   True    0.0.1     48s

If the control cluster doesn’t recognize the Wordpress instance type, it could be because the stack is still being installed. Wait a few seconds, and try creating the Wordpress instance again.

Wait

The Wordpress can take a while to spin up, because behind the scenes Crossplane is creating all of its dependendencies, which is a database and Kubernetes cluster. To check the status, you can use the trace command of the Crossplane CLI.

# Get the name of the Kubernetes Application resource which is the top level workload definiton for our Wordpress instance
K8S_APP_NAME=$(kubectl get -n app-project1-dev kubernetesapplication -lstack=sample-stack-wordpress -o=jsonpath='{.items[0].metadata.name}')

# Run the trace command
kubectl crossplane trace -n app-project1-dev kubernetesapplication "${K8S_APP_NAME}"

You can also check the status of individual Crossplane resources that Crossplane is creating for us:

# The claim for the database
kubectl get -n app-project1-dev mysqlinstance
# The claim for the Kubernetes cluster
kubectl get -n app-project1-dev kubernetescluster

# The workload definition
kubectl get -n app-project1-dev kubernetesapplication
# The things created on the Kubernetes cluster as part of the workload
kubectl get -n app-project1-dev kubernetesapplicationresource

For validation that these resources are spinning up, you can check in the usual way for your cloud provider, or you can ask for the statuses of some of the cloud-specific Kubernetes resources provided by the infrastructure stack that we installed.

For more information about how Crossplane manages databases and Kubernetes clusters for us, see the more complete documentation about claims, resource classes, and workloads.

Use

Once everything has been created, the ip address for the Wordpress instance will show up in the Crossplane KubernetesApplicationResource which represents the workload’s service. Here’s a way to watch for the ip:

kubectl get --watch kubernetesapplicationresource -n app-project1-dev -o custom-columns='NAME:.metadata.name,NAMESPACE:.spec.template.metadata.namespace,KIND:.spec.template.kind,SERVICE-EXTERNAL-IP:.status.remote.loadBalancer.ingress[0].ip'

The ip will show up on the one which has a Service kind.

If you navigate to the ip, you should see the Wordpress first-time start-up screen in your browser.

If you see it, things are working!

Clean up

When we want to get rid of everything, we can delete the Wordpress instance and let Crossplane and Kubernetes clean up the rest. To read more about how cleanup works, see the documentation on reclaim policies in Crossplane and garbage collection in Kubernetes.

To delete the Wordpress instance:

kubectl delete -n app-project1-dev wordpressinstance my-wordpressinstance

We can also remove the stack, using the Crossplane CLI:

kubectl crossplane stack uninstall sample-stack-wordpress -n app-project1-dev

Removing the stack removes any Wordpress instances that were created.

The cloud provider stack can also be removed using the kubectl crossplane stack uninstall command. Use kubectl crossplane stack list to see what’s installed.

Conclusion

We’re done!

In this guide, we:

Next steps

Crossplane can do a lot.

Now that we’ve gone through how to use a Crossplane Stack, you may want to learn more about which stacks are available, or about how to write your own stack.

To learn more about which stacks are available, check out the stack registry.

To learn more about how to write your own stack, see the stack developer guide.

References