Rewriting the GitHub Event Sample README

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.

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      <none>
+    ```
+
+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
+
+<!--TODO:
+explain the resources and communication channels, as well as where the secret
+is used. In particular include a note to look at
+https://github.com/<owner>/<repo>/settings/hooks to see the webhook registered
+and then deleted.
+ -->
 
 ## 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.