Skip to content

Latest commit

 

History

History
110 lines (80 loc) · 3.96 KB

CONTRIBUTING.md

File metadata and controls

110 lines (80 loc) · 3.96 KB
Raw

Contributing Guide

The Brigade CloudEvents Gateway is an official extension of the Brigade project and as such follows all of the practices and policies laid out in the main Brigade Contributor Guide. Anyone interested in contributing to this gateway should familiarize themselves with that guide first.

The remainder of this document only supplements the above with things specific to this project.

Running make hack-kind-up

As with the main Brigade repository, running make hack-kind-up in this repository will utilize ctlptl and KinD to launch a local, development-grade Kubernetes cluster that is also connected to a local Docker registry.

In contrast to the main Brigade repo, this cluster is not pre-configured for building and running Brigade itself from source, rather it is pre-configured for building and running this gateway from source. Because Brigade is a logical prerequisite for this gateway to be useful in any way, make hack-kind-up will pre-install a recent, stable release of Brigade into the cluster.

Running tilt up

As with the main Brigade repository, running tilt up will build and deploy project code (the gateway, in this case) from source.

For the gateway to successfully communicate with the Brigade instance in your local, development-grade cluster, you will need to execute the following steps before running tilt up:

  1. Log into Brigade:

    $ brig login -k -s https://localhost:31600 --root

    The root password is F00Bar!!!.

  2. Create a service account for the gateway:

    $ brig service-account create \
    --id cloudevents-gateway \
    --description cloudevents-gateway

  3. Copy the token returned from the previous step and export it as the BRIGADE_API_TOKEN environment variable:

    $ export BRIGADE_API_TOKEN=<token from previous step>

  4. Grant the service account permission to create events:

    $ brig role grant EVENT_CREATOR \
  --service-account cloudevents-gateway \
  --source brigade.sh/cloudevents

You can then run tilt up to build and deploy this gateway from source.

⚠️  Contributions that automate the creation and configuration of the service account setup are welcome.

Receiving Events Originating Locally

You can send CloudEvents from a local client to http://localhost:31700/events. The example does so using curl:

$ curl -i -k -X POST \
    -H "ce-specversion: 1.0" \
    -H "ce-id: 1234-1234-1234" \
    -H "ce-source: example/uri" \
    -H "ce-type: example.type" \
    -H "Authorization: Bearer insecure-dev-token" \
    http://localhost:31700/events

Receiving Events from External Services

Making the gateway that runs in your local, development-grade Kubernetes cluster visible to CloudEvent producers running elsewhere can be challenging. To help ease this process, our Tiltfile has built-in support for exposing your local gateway using ngrok. To take advantage of this:

  1. Sign up for a free ngrok account.

  2. Follow ngrok setup & installation instructions

  3. Set the environment variable ENABLE_NGROK_EXTENSION to a value of 1 before running tilt up.

  4. After running tilt up, the option should become available in the Tilt UI at http://localhost:10350/ to expose the gateway using ngrok. After going so, the applicable ngrok URL will be displayed in the gateway's logs in the Tilt UI.

  5. Use the URL <ngrok URL>/events and token(s) (shared secrets) from the Running tilt up section when configuring external CloudEvent producers to deliver CloudEvents to your gateway.

⚠️  We cannot guarantee that ngrok will work in all environments, especially if you are behind a corporate firewall.