Equinix Crossplane Provider

Teach the open-source CNCF Crossplane project how to build digital infrastructure on Equinix with the Equinix Crossplane provider.

What is it?

Build control planes without needing to write code. Crossplane has a highly extensible backend that enables you to orchestrate applications and infrastructure no matter where they run, and a highly configurable frontend that lets you define the declarative API it offers. (https://crossplane.io/, 2023/09/29)

That's Crossplane. What is the Equinix Crossplane Provider? It is the open-source provider for Crossplane that translates Kubernetes resources to Equinix API requests. The provider handles life-cycle management of resources.

Want a new Equinix Metal project? Create a Project Kubernetes custom resource.

Change the mutable properties of that Project resource and the Equinix resource will be immediately updated to match.

Ready to delete that project? Delete that same Kubernetes resource with kubectl delete.

Why do we love it?

Crossplane provides a unified control plane for managing cloud-native resources across multiple clouds, Kubernetes clusters, and other infrastructure providers. This simplifies the management and configuration of complex cloud-native environments.

Crossplane resources maintain a high fidelity relationship to the service provider API while feeling at home in Kubernetes. API experience is carried forward with custom resources providing a familiar interface. For example, an Equinix Metal Device resource in Kubernetes requires the same metro, plan, and operating_system fields to get started. However to fit in with Kubernetes naming conventions, you'll define operatingSystem in camel-case.

Using a declarative approach to managing resources means you can reliably re-provision infrastructure along with their dependent workloads. Combined with access controls, policy management, compositions, and auditing, Crossplane extends Kubernetes as an ever more capable platform for building platforms.

How do you use it?

Install Crossplane

You'll need a Kubernetes cluster to get started. If you don't have a Kubernetes cluster ready, you can create a lightweight Kind cluster or create a cluster on Equinix Metal using our Kubernetes Labs projects.

Once you have a cluster, make sure you have the Kubernetes client, kubectl, and Helm installed.

Follow the steps outlined at https://docs.crossplane.io/latest/software/install/ to get Crossplane added to your Kubernetes cluster.

Install the Equinix Provider

Once you have Crossplane's controller running, you'll need to install the Equinix provider to teach your cluster and Crossplane how to interact with the Equinix APIs.

Using kubectl apply create the following custom resource which will instruct Crossplane to install the Equinix provider:

cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-jet-equinix
spec:
  package: xpkg.upbound.io/equinix/provider-jet-equinix:v0.6.1
EOF

Create a Kubernetes Secret

You'll need to create a Kubernetes secret to reference in the provider configuration. This secret will contain the Equinix Metal API Token and Equinix Developer Portal Client ID and Secret for Fabric and Network Edge. For this example, if you won't be working with all of the services, you can only provide the relevant tokens and use a fake value for the others.

Start in your shell by capturing these values and environment variables. (You can skip the shell script configuration and use the YAML snippets directly by filling in the variables.)

read -s -p "Equinix Client ID: " EQUINIX_CLIENT_ID; echo
read -s -p "Equinix Client Secret: " EQUINIX_CLIENT_SECRET; echo
read -s -p "Metal Auth Token: " METAL_AUTH_TOKEN; echo

Then create the Secret resource in the crossplane-system namespace:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: example-creds
  namespace: crossplane-system
type: Opaque
stringData:
  credentials: |
    {
      "client_id": "$EQUINIX_CLIENT_ID",
      "client_secret": "$EQUINIX_CLIENT_SECRET",
      "auth_token": "$METAL_AUTH_TOKEN",
      "request_timeout": "30",
      "response_max_page_size": "100",
      "endpoint": "https://api.equinix.com"
    }
EOF

Create the cluster-scoped Equinix ProviderConfig referencing the secret:

cat <<EOF | kubectl apply -f -
apiVersion: equinix.jet.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      name: example-creds
      namespace: crossplane-system
      key: credentials
EOF

Create an Equinix Metal Project

Since we'll be taking a few shortcuts in this example, make sure your Public SSH Key is registered with your Equinix Metal profile before continuing.

Create a new upjet-example-project project in Equinix Metal:

cat <<EOF | kubectl apply -f -
apiVersion: metal.equinix.jet.crossplane.io/v1alpha1
kind: Project
metadata:
 name: upjet-example-project
spec:
 forProvider:
   name: upjet-example-project
 providerConfigRef:
   name: default
EOF

Create an Equinix Metal Server

With Crossplane, we can reference the Equinix Metal API identifier of the newly created project. Let's create a server in that project.

The following snippet will provision a c3.small.x86 in Dallas running Ubuntu:

cat <<EOF | kubectl apply -f -
apiVersion: metal.equinix.jet.crossplane.io/v1alpha1
kind: Device
metadata:
  name: upjet-example
spec:
  forProvider:
    projectIdRef:
      name: upjet-example-project
    metro: da
    hostname: upjet-example
    plan: c3.small.x86
    operatingSystem: ubuntu_20_04
    billingCycle: hourly
    tags:
    - crossplane
  providerConfigRef:
    name: default
  writeConnectionSecretToRef:
    name: upjet-example
    namespace: crossplane-system
EOF

Watch the device provision in the cluster using kubectl get:

kubectl get -o wide device/upjet-example

You can see all Equinix resources managed by Crossplane at a glance with kubectl get equinix.

$ kubectl get equinix -o wide
NAME                                                   READY   SYNCED   EXTERNAL-NAME                          AGE
device.metal.equinix.jet.crossplane.io/upjet-example   True    True     efb8e607-46f8-46e2-b765-650f597c7d50   4m34s

NAME                                                            READY   SYNCED   EXTERNAL-NAME                          AGE
project.metal.equinix.jet.crossplane.io/upjet-example-project   True    True     81d125ab-f6b2-441e-95cb-a2cfab1ceb05   87m

Additional Information

This basic example shows how you can get started with Crossplane on Equinix.

For more complex use-cases, including compositions, you'll want to refer to the Crossplane documentation and the reference documentation for the Equinix provider hosted in the Upbound Marketplace.