Crossplane Ansible Provider: Getting Started

Today we are very excited to announce a new open source project, provider-ansible, a Crossplane provider designed to extend the Crossplane scope by enabling its integration with Ansible.

Why Ansible Crossplane Provider

Ansible is a popular automation technology. It is widely adopted by many IT organizations nowadays to automate management for their IT systems, ranging from non cloud native to cloud native. It has a very mature community and an ecosystem with many existing automation assets that are publicly available at https://galaxy.ansible.com/. In the meantime, many IT organizations have their own private Ansible assets accumulated for years to address their specific IT management requirements.

On the other hand, Crossplane, as a cloud native control plane framework, has evolved rapidly in recent years and now has become a very active CNCF project. It allows people to drive IT automation in a cloud native manner and orchestrate management automation for different varieties of IT resources using its powerful composition engine. All these can happen inside a Kubernetes cluster.

To combine the two powerful tools together and unleash the synergy, we have built a Crossplane provider for Ansible. It works as a bridge that can connect the two communities.

If you are familiar with Ansible and want to get benefits from what Crossplane provides, the Crossplane provider for Ansible is definitely a good option for you! For example, you can use this provider to drive Ansible automation inside a Kubernetes cluster rather than from the command line. By doing so, your Ansible automation can work with some modern IT operation methodology such as GitOps seamlessly. You can also use this provider to orchestrate multiple resource management automation approaches including Ansible using Crossplane’s composition mechanism. This will allow you to mix the use of many great automation assets from both two communities consistently.

This provider also opens a door to IT organizations who may have already invested lots of money on their IT systems management automation by using Ansible, including those traditional systems that do not behave cloud-natively, and want to adopt Crossplane without losing their investments. They can now reuse their existing automation assets without reinventing the wheels, specifically in some case when there’s no easy replacement for their traditional automation assets in Crossplane community in cloud native world. For example, to provision a VM in a LAN and install something on that is easy to be done by Ansible, but in Crossplane, it may need to introduce a new provider which is not necessary especially when people have some Ansible assets in place already.

In the next few sections, you will learn how the Crossplane provider for Ansible works at an architectural level in order to enable the above use cases. You will also learn how to drive Ansible execution using this provider by going through a couple of concrete examples step by step. Keep reading!

Understanding How It Works

The Ansible provider execution is driven by the Crossplane ecosystem.

In Fig.1, we see the high level architecture for the Ansible provider: it uses Kubernetes resource AnsibleRun to leverage Ansible content, e.g.: Playbook, Role, etc., to do the actual work. The AnsibleRun resource refers to the ProviderConfig resource which includes the required information for the proper functioning of our Ansible provider, e.g.: credentials, requirements, behavior variables, etc.

Within the Crossplane reconciliation process, the Ansible provider relies on standard Ansible binaries to execute the job: it uses the ansible-galaxy cli to download Ansible contents specified in the AnsibleRun resource using credentials from ProviderConfig resource, then depending on different run policy specified, it will invoke ansible-runner cli to execute them at different time.

The Hello World Example

In this section, let’s start with a very simple example to explore the basic use of Ansible provider. Our first example is the hello world Ansible playbook which will print a “Hello world!” message to the console.

To demonstrate the use of Ansible provider, let’s start a KIND cluster at first. KIND is a local Kubernetes cluster using Docker container “nodes”. To start the cluster, you need KIND CLI. For more information on KIND, please refer to https://kind.sigs.k8s.io/.

Run below command to start the cluster:

Then, install Crossplane into the cluster:

And the Crossplane CLI, which is essentially a kubectl plugin that extends kubectl with functionality to build, push, and install Crossplane packages:

Then, run below command to install the Ansible provider:

After the provider is installed, you can run below command to verify if the installation is successful:

If everything works fine, you should see that both the column INSTALLED and HEALTHY for the Provider resource are True. For example:

After then, apply the following YAML manifests which include a ProviderConfig and an AnsibleRun:

In this example, we do not really need any real credential to access a remote repository that hosts Ansible roles or playbooks, so the spec.credentials field in ProviderConfig is empty. For AnsibleRun, we define the hello world playbook as an inline playbook by spec.forProvider.playbookInline. After applying these YAML manifests, you will see something similar to the following in the Ansible provider pod logs:

As you can see, the hello world message was printed out to the console. This is exactly the same as you see when running Ansible playbook from command line, the only difference is that you can now drive the Ansible run in a cloud native way by applying a Kubernetes custom resource and customizing the run by modifying the custom resource at runtime.

A More Powerful Example

In this section, we are introducing a more complex custom resource. Our example target is to create and maintain a GCP bucket.

First of all we need to create a Kubernetes secret that handles the provider credentials, GCP in this case.

Then we should introduce this secret in the ProviderConfig resource which is used to authenticate against upstream API and repositories:

Once we create ProviderConfig ressource, the last step is always to create the AnsibleRun resource: