Integrating Equinix Metal events

Modified on Thu, 25 May, 2023 at 12:14 PM

TABLE OF CONTENTS

Overview of the Equinix Receiver
Configuring the Equinix receiver
Installing the Equinix receiver
Testing the Equinix receiver

Overview of the Equinix Receiver

It’s pretty simple, the Direktiv receiver will connect to the Equinix Metal API using an Authentication Token created in the console. The receiver will pull all of the events from the Project level and the Device level.

NOTE: sadly, the API does NOT support any filter-by-date-time function or any form of subscription based notification. The receiver keeps track of what events have been sent based on the start-time of the receiver (so we don’t receive old events) and a correlation of received vs. sent events. It’s certainly something the Equinix team can improve on.

The events are then converted into CloudEvents and injected into the Direktiv event management engine. From this point forward … it’s all up to your imagination.

Configuring the Equinix receiver

The receiver is installed and configured using the following YAML file:

apiVersion: v1
kind: ConfigMap
metadata:
  name: equinix-receiver-cfg-cm
data:
  config.yaml: |
    equinix:
      organizationId: <equinix organization id>
      packetAuthToken: <equinix metal authentication token>

    direktiv:
      endpoint: https://<<direktiv-url>>/api/namespaces/<<namespace>>/broadcast
      insecureSkipVerify: true
      token: <<direktiv-token>>
      event-on-error: true
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: equinix-receiver
  labels:
    app: equinix-receiver
spec:
  replicas: 1
  selector:
    matchLabels:
      app: equinix-receiver
  template:
    metadata:
      annotations:
        linkerd.io/inject: disabled
      labels:
        app: equinix-receiver
    spec:
      volumes:
      - name: equinixconf
        configMap:
          name: equinix-receiver-cfg-cm
      securityContext:
        runAsNonRoot: true
        runAsUser: 65532        
        runAsGroup: 65532
      containers:
        - name: equinix-receiver
          image: gcr.io/direktiv/receivers/equinix-receiver:1.0
          imagePullPolicy: Always
          # ports:
          #   - containerPort: 2525
          volumeMounts:
          - name: equinixconf
            mountPath: "/config"
            readOnly: false

The following information is needed:

organizationId: the organization ID can be found in the Equinix Metal console, under the Organization’s information page

packetAuthToken: the authentication token can be generated from your profile page. Note that the token can also be created on the Project level, but the listener will not be able to connect to all of the Projects to collect events.

endpoint: just add you Direktiv URL and the namespace you want the events to be sent to (e.g. https://equinix.direktiv.io/api/namespaces/equinix-workflows/broadcast)
token: this is your Direktiv authentication token, created on the namespace level and given the appropriate permissions (eventSend)

For more information on permissions, see this Knowledge Base article

Installing the Equinix receiver

For this blog article, I’m going to assume you have a Direktiv instance available and access to kubectl to install the receiver.

Create the YAML file as described above. In this case, I called it equinix-receiver.yaml with the following configuration:

apiVersion: v1
kind: ConfigMap
metadata:
  name: equinix-receiver-cfg-cm
data:
  config.yaml: |
    equinix:
      organizationId: ed49fa53-743f-43aa-836b-e24f88f94d9c
      packetAuthToken: ozDWMz.............1VcpUmwj4AM

    direktiv:
      endpoint: https://equinix.direktiv.io/api/namespaces/equinix-workflows/broadcast
      insecureSkipVerify: true
      token: v4.........MZnFF_2VwgkG0Xmg
      event-on-error: true
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: equinix-receiver
  labels:
    app: equinix-receiver
spec:
  replicas: 1
  selector:
    matchLabels:
      app: equinix-receiver
  template:
    metadata:
      annotations:
        linkerd.io/inject: disabled
      labels:
        app: equinix-receiver
    spec:
      volumes:
      - name: equinixconf
        configMap:
          name: equinix-receiver-cfg-cm
      securityContext:
        runAsNonRoot: true
        runAsUser: 65532
        runAsGroup: 65532
      containers:
        - name: equinix-receiver
          image: gcr.io/direktiv/receivers/equinix-receiver:1.0
          imagePullPolicy: Always
          # ports:
          #   - containerPort: 2525
          volumeMounts:
          - name: equinixconf
            mountPath: "/config"
            readOnly: false

Next step, simply run the following command:

kubectl apply -f equinix-reciever.yaml

The command produces the output:

configmap/equinix-receiver-cfg-cm created
deployment.apps/equinix-receiver created

This will install the receiver. You can verify that it’s all up and running:

# kubectl get pods
NAME                                          READY   STATUS    RESTARTS   AGE
direktiv-api-6f8567555b-pq7q8                 2/2     Running   0          10d
direktiv-flow-564c8fc4cc-jh5dh                3/3     Running   0          10d
direktiv-functions-6f6698d7fb-s7n9z           2/2     Running   0          10d
direktiv-prometheus-server-667b8c6d65-6nzxm   3/3     Running   0          10d
direktiv-ui-d947dccc-zlzxc                    2/2     Running   0          10d
equinix-receiver-f8d45d687-qxdxw              1/1     Running   0          4s
knative-operator-58647bbfd5-w9kvc             1/1     Running   0          10d
operator-webhook-b866dc4c-6klqx               1/1     Running   0          10d

Testing the Equinix receiver

The simplest way to test the receiver is to do something that will trigger an event in Equinix Metal console. In this example — I deleted a machine:

In Direktiv we can see the event received in the namespace:

And the input information coming in (looking at event provisioning.110):

{
  "provisioning.110": {
    "data": {
      "body": "Provision complete! Your device is ready to go.",
      "created_at": "2023-02-10T03:56:32Z",
      "href": "/metal/v1/events/cbe6eed5-b2ac-4bdb-bd82-b7b88866e200",
      "id": "cbe6eed5-b2ac-4bdb-bd82-b7b88866e200",
      "interpolated": "Provision complete! Your device is ready to go.",
      "relationships": [
        {
          "href": "#0caf4d6d-fafc-470b-86b1-d889eb838afa"
        }
      ],
      "type": "provisioning.110"
    },
    "hostname": "c3-small-x86-01",
    "id": "d7d2ce0f-b63f-4c67-9629-2d7db5bd1298",
    "orgid": "ed49fa53-743f-43aa-836b-e24f88f94d9c",
    "orgname": "Direktiv",
    "projid": "d894d0eb-2b6c-4741-b106-c7cb76018d32",
    "projname": "Direktiv EKS Project",
    "source": "direktiv/listener/equinix/Direktiv/Direktiv%20EKS%20Project",
    "specversion": "1.0",
    "traceparent": "00-41bf58306274f26d0089209b0ad17caf-d3dd31d5d1f79415-00",
    "type": "provisioning.110"
  }
}

The information for each event is different, but the type definition identifies the event name and the corresponding event in Equinix Metal console.