diff --git a/sample/github/Dockerfile b/sample/github/Dockerfile new file mode 100644 index 00000000000..5953e7901e5 --- /dev/null +++ b/sample/github/Dockerfile @@ -0,0 +1,33 @@ +# Copyright 2018 The Knative Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +FROM golang AS builder + +WORKDIR /go/src/github.com/knative/docs/ +ADD . /go/src/github.com/knative/docs/ + +RUN CGO_ENABLED=0 go build ./eventing/samples/github-events + +FROM gcr.io/distroless/base + +COPY --from=builder /go/src/github.com/knative/docs/github-events /sample + +ENTRYPOINT ["/sample"] +EXPOSE 8080 + + +# TODO: FIX IN DOCS REPO: +# Dockerfile pathing is relative to the dockerfile itself which causes two issues here: +# this github-events directory's contents gets placed under /go/src/github.com/knative/docs/ which results in an unable to find eventing/samples/github-events error when compiling. This can be fixed by changing the above command to ADD . /go/src/github.com/knative/docs/eventing/samples/github-events +# Because we are only copying the github-events dir we lack the deps for this example (which are in docs/vendor). ISTM we can either add them with go get or add dep to the docker image along with a Gopkg config and then run dep ensure. \ No newline at end of file diff --git a/sample/github/README.md b/sample/github/README.md index af796115b44..11448404e85 100644 --- a/sample/github/README.md +++ b/sample/github/README.md @@ -6,156 +6,157 @@ deployed to receive the webhook's event deliveries and forward them into a `Flow` resource takes care of provisioning the webhook, the `Service`, the `Channel`, and the `Subscription`. -## Prerequisites - -1. [Setup your development environment](../../DEVELOPMENT.md#getting-started) -2. [Start Knative](../../README.md#start-knative) -3. For GitHub to be able to call into the cluster, - [configure a custom domain](https://github.com/knative/docs/blob/master/serving/using-a-custom-domain.md) and - [assign a static IP address](https://github.com/knative/docs/blob/master/serving/gke-assigning-static-ip-address.md). -4. Install a ClusterBus - -update `knative/eventing/config/buses/stub-bus.yaml`, changing `kind` to `ClusterBus`, like: - -```yaml -apiVersion: channels.knative.dev/v1alpha1 -kind: ClusterBus -metadata: - name: stub -spec: - dispatcher: - name: dispatcher - image: github.com/knative/eventing/pkg/buses/stub - args: [ - "-logtostderr", - "-stderrthreshold", "INFO", - ] -``` - -and apply the stub bus - -```shell -ko apply -f config/buses/stub -``` - -5. Install GitHub as an event source - -```shell -ko apply -f pkg/sources/github/ -``` - -5. Check that the GitHub is now showing up as an event source and there's an event type for *pullrequests* - -```shell -kubectl get eventsources -kubectl get eventtypes -``` - -6. Create a [personal access token](https://github.com/settings/tokens) to GitHub repo that you can use to register - webhooks with the GitHub API. Also decide on a token that your code will use to authenticate the incoming webhooks - from GitHub (*accessToken*). Update `sample/github/githubsecret.yaml` with those values. If your generated access - token is `'asdfasfdsaf'` and you choose your *secretToken* as `'password'`, you'd modify - `sample/github/githubsecret.yaml` like so: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: githubsecret -type: Opaque -stringData: - githubCredentials: > - { - "accessToken": "asdfasfdsaf", - "secretToken": "password" - } -``` - -## Running - -In response to a pull request event, the _legit_ Service will add `(looks pretty legit)` to the PR title. - -Deploy the _legit_ service via: - -```shell -ko apply sample/github/legit-service.yaml -``` - -Once deployed, you can inspect the created resources with `kubectl` commands: +In response to a pull request event, the sample app _legit_ Service will add +`(looks pretty legit)` to the PR title. -```shell -# This will show the Service that we created: -kubectl get service.serving.knative.dev -o yaml - -# This will show the Route that the Service created: -kubectl get route -o yaml - -# This will show the Configuration that the Service created: -kubectl get configurations -o yaml - -# This will show the Revision that was created by the Configuration: -kubectl get revisions -o yaml -``` - -The `Flow` will accept the Webhook calls from GitHub and pass them to the _legit_ service. +## Prerequisites -You can inspect those resources with the following `kubectl` commands: +- A Kubernetes cluster with Knative serving installed. Follow the + [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + if you need to create one. +- [Docker](https://www.docker.com/) installed and running on your local machine, + and a Docker Hub account configured (you'll use it for a container registry). +- The Kubernetes cluster also has Knative eventing core installed. You can + install with: + ```shell + kubectl apply -f https://storage.googleapis.com/knative-releases/eventing/latest/release.yaml + ``` +- A domain name that allows GitHub to call into the cluster: Follow the + [configure a custom domain](https://github.com/knative/docs/blob/master/serving/using-a-custom-domain.md) and + [assign a static IP address](https://github.com/knative/docs/blob/master/serving/gke-assigning-static-ip-address.md) + instructions. + +## Configuring Knative + +To use this sample, you'll need to install the `stub` ClusterBus and the +`github` EventSource. ```shell -# This will show the available EventSources that you can generate feeds from: -kubectl get eventsources -o yaml - -# This will show the available EventTypes that you can generate feeds from: -kubectl get eventtypes -o yaml +kubectl apply -f https://storage.googleapis.com/knative-releases/eventing/latest/release-clusterbus-stub.yaml +kubectl apply -f https://storage.googleapis.com/knative-releases/eventing/latest/release-source-github.yaml ``` -Configure the `Flow` to point to a GitHub repository you are able to control and update -`spec.trigger.resource` in `samples/github/flow.yaml`. - -And then apply the resources: - -```shell -ko apply -f sample/github/auth.yaml -ko apply -f sample/github/flow.yaml -``` - -Once deployed, you can inspect the created resources with `kubectl` commands: - -```shell -# This will show the available Flows we created: -kubectl get flows -o yaml - -# This will show the available Feeds created from the Flow: -kubectl get feeds -o yaml - -# This will show the available Channels created from the Flow: -kubectl get channels -o yaml +## Granting permissions -# This will show the available Subscriptions created from the Flow: -kubectl get subscriptions -o yaml +Because the `github` EventSource needs to create a Knative Service, you'll need +to provision a special ServiceAccount with the necessary permissions. -# This will show the available ClusterBuses we created in the prerequisites: -kubectl get clusterbuses -o yaml -``` - -Then create the secret so that you can see changes: +The `eventing/samples/github-events/auth.yaml` file provisions a service +account, and creates a role which can create a Knative Service in the `default` +namespace. In a production environment, you might want to limit the access of +this service account to only specific namespaces. ```shell - ko apply -f sample/github/githubsecret.yaml +kubectl apply -f eventing/samples/github-events/auth.yaml ``` -Then create a PR for the repo you configured the webhook for, and you'll see that the Title -will be modified with the suffix '(looks pretty legit)' +## Build and deploy the sample + +1. Use Docker to build the sample code into a container. To build and push with + Docker Hub, run these commands replacing `{username}` with your Docker Hub + username. Run the following from the _root_ of the `knative/docs` repo: + + ```shell + # Build the container on your local machine + docker build -t {username}/github-events --file=eventing/samples/github-events/Dockerfile . + + # Push the container to docker registry + docker push {username}/github-events + ``` + +1. After the build has completed and the container is pushed to Docker Hub, you + can deploy the function into your cluster. **Ensure that the container image + value in `function.yaml` matches the container you built in the previous + step.** Apply the configuration using `kubectl`: + + ```shell + kubectl apply -f eventing/samples/github-events/function.yaml + ``` + +1. Check that your service is running using: + + ```shell + kubectl get services.serving.knative.dev -o "custom-columns=NAME:.metadata.name,READY:.status.conditions[2].status,REASON:.status.conditions[2].message" + NAME READY REASON + legit True + ``` + +1. Create a [personal access token](https://github.com/settings/tokens) to + GitHub repo that the GitHub source can use to register webhooks with the + GitHub API. Also decide on a token that your code will use to authenticate + the incoming webhooks from GitHub (*accessToken*). + + The token can be named anything you find convenient. This sample requires + full `repo` control to be able update the title of the _Pull Request_. + The Source requires `admin:repo_hook`, this allows it to create webhooks + into repos that your account is allowed to do so. Copy and save this token; + GitHub will force you to generate it again if misplaced. + + Here I named my token "EventingSample" and have selected the recommended + scopes: + + ![GitHub UI](personal_access_token.png "GitHub personal access token screenshot") + + Update `eventing/samples/github-events/githubsecret.yaml` with those + values. If your generated access token is `'asdfasfdsaf'` and you choose + your *secretToken* as `'personal_access_token_value'`, you'd modify + `eventing/samples/github-events/githubsecret.yaml` like so: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: githubsecret + type: Opaque + stringData: + githubCredentials: > + { + "accessToken": "asdfasfdsaf", + "secretToken": "personal_access_token_value" + } + ``` + + Hint: you can makeup a random *accessToken* with: + + ```shell + head -c 8 /dev/urandom | base64 + ``` + + Then, apply the githubsecret using `kubectl`: + + ```shell + kubectl apply -f eventing/samples/github-events/githubsecret.yaml + ``` + +1. Create the flow sending GitHub Events to the service: + + ```shell + kubectl apply -f eventing/samples/github-events/flow.yaml + ``` + +1. Create a PR for the repo you configured the webhook for, and you'll see that + the Title will be modified with the suffix `(looks pretty legit)` + + +## Understanding what happened + + ## Cleaning up -To clean up the sample `Flow`: -```shell - ko delete -f sample/github/flow.yaml -``` - -And you can check the repo and see the webhook has been removed +To clean up the function, `Flow`, auth, and secret: ```shell -ko delete -f sample/github/ +kubectl delete -f eventing/samples/github-events/function.yaml +kubectl delete -f eventing/samples/github-events/flow.yaml +kubectl delete -f eventing/samples/github-events/auth.yaml +kubectl delete -f eventing/samples/github-events/githubsecret.yaml ``` + +And then delete the [personal access token](https://github.com/settings/tokens) +created from GitHub. diff --git a/sample/github/legit.go b/sample/github/function.go similarity index 100% rename from sample/github/legit.go rename to sample/github/function.go diff --git a/sample/github/legit-service.yaml b/sample/github/function.yaml similarity index 100% rename from sample/github/legit-service.yaml rename to sample/github/function.yaml diff --git a/sample/github/personal_access_token.png b/sample/github/personal_access_token.png new file mode 100644 index 00000000000..8f03ecc1d07 Binary files /dev/null and b/sample/github/personal_access_token.png differ