Skip to content

Commit

Permalink
update docs to put focus on use (#81)
Browse files Browse the repository at this point in the history 
Signed-off-by: Kent Rancourt <[email protected]>
  • Loading branch information
@krancour
krancour committed May 24, 2022
1 parent d66f6fa commit dbc772d
Show file tree
Hide file tree
Showing 3 changed files with 176 additions and 177 deletions.
31 changes: 10 additions & 21 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,43 +62,32 @@ _before_ running `tilt up`:
--source brigade.sh/cloudevents
```

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

1. Edit the `tokens` section of `charts/brigade-cloudevents-gateway/values.yaml`
to map cloudevent sources to tokens (shared secrets) that clients can use to
authenticate to your gateway. See
[this section](./README.md#2-install-the-cloudevents-gateway) of `README.md`
for more information.

> ⚠️&nbsp;&nbsp;Take care not to include modifications to the `values.yaml`
> file in any PRs you open.

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

> ⚠️&nbsp;&nbsp;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 below utilizes `curl`. Be sure to substitute an appropriate token
from the previous section in the `Authorization` header.
You can send CloudEvents from a local client to `http://localhost:31700/events`.
The example does so using `curl`:

```shell
$ 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 MySharedSecret" \
-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 services running elsewhere that may deliver cloudevents can be
challenging. To help ease this process, our `Tiltfile` has built-in support for
exposing your local gateway using [ngrok](https://ngrok.com/). To take advantage
of this:
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](https://ngrok.com/). To take advantage of this:

1. [Sign up](https://dashboard.ngrok.com/signup) for a free ngrok account.

Expand All @@ -115,7 +104,7 @@ of this:
1. Use the URL `<ngrok URL>/events` and token(s) (shared secrets) from the
[Running `tilt up` section](#running-tilt-up) when configuring external
services to deliver cloudevents to your gateway.
CloudEvent producers to deliver CloudEvents to your gateway.
> ⚠️&nbsp;&nbsp;We cannot guarantee that ngrok will work in all environments,
> especially if you are behind a corporate firewall.
187 changes: 31 additions & 156 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,145 +7,34 @@

<img width="100" align="left" src="logo.png">

This is a work-in-progress
[Brigade 2](https://github.com/brigadecore/brigade/tree/v2)
compatible gateway that receives [CloudEvents](https://cloudevents.io/) over
HTTP/S and propagates them into Brigade 2's event bus.
The Brigade CloudEvents Gateway receives webhooks from any
[CloudEvents 1.0](https://cloudevents.io/) event producer and emits them into
Brigade's event bus.

<br clear="left"/>

## Installation

Prerequisites:

* A Kubernetes cluster:
* For which you have the `admin` cluster role
* That is already running Brigade 2.6.0+
* Capable of provisioning a _public IP address_ for a service of type
`LoadBalancer`. (This means you won't have much luck running the gateway
locally in the likes of kind or minikube unless you're able and willing to
mess with port forwarding settings on your router, which we won't be
covering here.)

* `kubectl`, `helm` (commands below require Helm 3.7.0+), and `brig` (the
Brigade 2 CLI)

### 1. Create a Service Account for the Gateway

__Note:__ To proceed beyond this point, you'll need to be logged into Brigade 2
as the "root" user (not recommended) or (preferably) as a user with the `ADMIN`
role. Further discussion of this is beyond the scope of this documentation.
Please refer to Brigade's own documentation.

Using Brigade 2's `brig` CLI, create a service account for the gateway to use:

```shell
$ brig service-account create \
--id brigade-cloudevents-gateway \
--description brigade-cloudevents-gateway
```

Make note of the __token__ returned. This value will be used in another step.
_It is your only opportunity to access this value, as Brigade does not save it._

Authorize this service account to create new events:

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

__Note:__ The `--source brigade.sh/cloudevents` option specifies that this
service account can be used _only_ to create events having a value of
`brigade.sh/cloudevents` in the event's `source` field. _This is a security
measure that prevents the gateway from using this token for impersonating other
gateways._

### 2. Install the CloudEvents Gateway

For now, we're using the [GitHub Container Registry](https://ghcr.io) (which is
an [OCI registry](https://helm.sh/docs/topics/registries/)) to host our Helm
chart. Helm 3.7 has _experimental_ support for OCI registries. In the event that
the Helm 3.7 dependency proves troublesome for users, or in the event that this
experimental feature goes away, or isn't working like we'd hope, we will revisit
this choice before going GA.

First, be sure you are using
[Helm 3.7.0](https://github.com/helm/helm/releases/tag/v3.7.0) or greater and
enable experimental OCI support:

```shell
$ export HELM_EXPERIMENTAL_OCI=1
```

As this chart requires custom configuration as described above to function
properly, we'll need to create a chart values file with said config.

Use the following command to extract the full set of configuration options into
a file you can modify:

```shell
$ helm inspect values oci://ghcr.io/brigadecore/brigade-cloudevents-gateway \
--version v0.4.1 > ~/brigade-cloudevents-gateway-values.yaml
```

Edit `~/brigade-cloudevents-gateway-values.yaml`, making the following changes:

* `host`: Set this to the host name where you'd like the gateway to be
accessible.

* `brigade.apiAddress`: Address of the Brigade API server, beginning with
`https://`

* `brigade.apiToken`: Service account token from step 2

* `service.type`: If you plan to enable ingress (advanced), you can leave this
as its default -- `ClusterIP`. If you do not plan to enable ingress, you
probably will want to change this value to `LoadBalancer`.

* `tokens`: This field should define tokens that can be used by clients to send
events (webhooks) to this gateway. Note that keys are completely ignored by
the gateway and only the values (tokens) matter. The keys only serve as
recognizable token identifiers for human operators.

Save your changes to `~/brigade-cloudevents-gateway-values.yaml` and use the following command to install
the gateway using the above customizations:

```shell
$ helm install brigade-cloudevents-gateway \
oci://ghcr.io/brigadecore/brigade-cloudevents-gateway \
--version v0.4.1 \
--create-namespace \
--namespace brigade-cloudevents-gateway \
--values ~/brigade-cloudevents-gateway-values.yaml \
--wait \
--timeout 300s
```

### 3. (RECOMMENDED) Create a DNS Entry

If you overrode defaults and set `service.type` to `LoadBalancer`, use this
command to find the gateway's public IP address:

```shell
$ kubectl get svc brigade-cloudevents-gateway \
--namespace brigade-cloudevents-gateway \
--output jsonpath='{.status.loadBalancer.ingress[0].ip}'
```

If you overrode defaults and enabled support for an ingress controller, you
probably know what you're doing well enough to track down the correct IP without
our help. 😉

With this public IP in hand, edit your name servers and add an `A` record
pointing your domain to the public IP.

### 4. Add a Brigade Project

You can create any number of Brigade projects (or modify an existing one) to
listen for CloudEvents that were sent to your gateway and, in turn, emitted into
Brigade's event bus:
After [installation](docs/INSTALLATION.md), follow the documentation for any
CloudEvents 1.0 event producer to send CloudEvents to this gateway. Do not
forget to utilize one of the bearer tokens you created during the installation
process for authentication.

Subscribe any number of Brigade
[projects](https://docs.brigade.sh/topics/project-developers/projects/)
to the events emitted by this component -- all of which have a value of
`brigade.sh/cloudevents` in their `source` field and a value of `cloudevent` in
their `type` field.

> ⚠️&nbsp;&nbsp;Because CloudEvents and Brigade events both utilize `source` and
> `type` fields, this gateway adds the values of the CloudEvent's original
> `source` and `type` fields to the native Brigade event as
> [qualifiers](https://docs.brigade.sh/topics/project-developers/events/#qualifiers)
> with the keys `source` and `type`, respectively. The original CloudEvent, in
> its entirety, is added to the the native Brigade event's `payload` field.
In the example project definition below, we subscribe to events from this
gateway (identified by `source: brigade.sh/cloudevents` and `type: cloudevent`)
that originated from an "upstream" CloudEvent producer that labeled its events
with source `example/uri` and type `example.type`:

```yaml
apiVersion: brigade.sh/v2
Expand Down Expand Up @@ -180,10 +69,11 @@ so:
$ brig project create --file project.yaml
```

### 5. Create a CloudEvent
## Try it Out

You can use the following `curl` command to send a CloudEvent that should be
subscribed to by the example project in the previous section:
You can use the following `curl` command to send a simulated CloudEvent to the
gateway. This event is subscribed to by the example project in the previous
section.

```shell
$ curl -i -k -X POST \
Expand Down Expand Up @@ -212,34 +102,19 @@ Content-Length: 0
```

To confirm that the gateway emitted a corresponding Brigade event into Brigade's
event bus, list the events for the `cloudevents-demo` project (created in
section 4), which is subscribed to such events:
event bus, list the events for the `cloudevents-demo` project:

```shell
$ brig event list --project cloudevents-demo
```

If this all works out, you should be equally successful wiring CloudEvents from
any CloudEvents 1.0-compliant provider into your Brigade instance.
any CloudEvents 1.0 producer into your Brigade instance.

Full coverage of `brig` commands is beyond the scope of this documentation, but
at this point, additional `brig` commands can be applied to monitor the event's
status and view logs produced in the course of handling the event.

## Events Received and Emitted by this Gateway

CloudEvents received by this gateway are emitted into Brigade's event bus as
native Brigade events with source `brigade.sh/cloudevents` and type
`cloudevent`. The CloudEvent's original source and type are added to the native
Brigade event as qualifiers with the keys `source` and `type`, respectively. The
CloudEvent's original data (taken from a `data` field in the request body)
becomes the value of the native Brigade event's `payload` field.

## Examples Projects

See `examples/` for complete Brigade projects that demonstrate various
scenarios.

## Contributing

The Brigade project accepts contributions via GitHub pull requests. The
Expand Down
Loading

0 comments on commit dbc772d

Please sign in to comment.