diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bec15e1201..5112d1ef00 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,14 +14,38 @@ Open an issue. Please include descriptions of the following: - Create a new issue to start a discussion around new topic. Label the issue as `new-feature` ## Setup your DEV environment +Argo Events is native to Kubernetes so you'll need a running Kubernetes cluster. This guide includes steps for `Minikube` for local development, but if you have another cluster you can ignore the Minikube specific step 3. ### Requirements - Golang 1.10 - Docker - dep -### Quickstart -See the [quickstart guide](./docs/quickstart.md) for help in getting started. +### Installation & Setup + +#### 1. Get the project +``` +go get github.com/argoproj/argo-events +cd $GOPATH/src/github.com/argoproj/argo-events +``` + +#### 2. Vendor dependencies +``` +dep ensure -vendor-only +``` + +#### 3. Start Minikube and point Docker Client to Minikube's Docker Daemon +``` +minikube start +eval $(minikube docker-env) +``` + +#### 5. Build the project & Docker images +``` +make all +``` + +Follow the rest of the [quickstart guide](docs/quickstart.md) to install components. ## Changing Types If you're making a change to the `pkg/apis/sensor/v1alpha1` package, please ensure you re-run the K8 code-generator scripts found in the `/hack` folder. First, ensure you have the `generate-groups.sh` script at the path: `vendor/k8s.io/code-generator/`. Next run the following commands in order: diff --git a/README.md b/README.md index 92b6ce2559..61b9ab6b4c 100644 --- a/README.md +++ b/README.md @@ -22,5 +22,5 @@ Argo Events is a Kubernetes CRD which can manage dependencies using kubectl comm - [Learn about signals](./docs/signal-guide.md) - [Learn about triggers](./docs/trigger-guide.md) - [Getting started](./docs/quickstart.md) -- [Want to contribute?](./CONTRIBUTING.md) +- [Want to contribute or develop/run locally?](./CONTRIBUTING.md) - See where the project is headed in the [roadmap](./ROADMAP.md) diff --git a/docs/quickstart.md b/docs/quickstart.md index 98e11b34f4..ac741f39d6 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,95 +1,76 @@ # Getting Started - Quickstart -This is a guide to getting started with Argo Events using Minikube. +This is a guide to getting started with Argo Events. ## Requirements +* Kubernetes cluster >v1.9 * Installed the [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) command-line tool >v1.9.0 -* Have a [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) file (default location is `~/.kube/config`). -* Installed Minikube >v0.26.1 -* Installed Go >1.9 and properly setup the [GOPATH](https://golang.org/doc/install) +* Installed Go >1.9 and properly setup the [GOPATH](https://golang.org/doc/install) environment variable * Installed [dep](https://golang.github.io/dep/docs/installation.html), Go's dependency tool -## 1. Checkout project's master branch +## 1. Get the project ``` -$ git clone git@github.com:argoproj/argo-events.git +go get github.com/argoproj/argo-events +cd $GOPATH/src/github.com/argoproj/argo-events ``` -## 2. Install vendor dependencies -``` -$ dep ensure -vendor-only -``` - -## 3. Start Minikube -``` -$ minikube start -``` - -## 4. Point Docker Client to Minikube's Docker Daemon -``` -$ eval $(minikube docker-env) -``` - -## 5. Build the project & Docker images -``` -$ cd go/src/github.com/argoproj/argo-events -$ make all -``` - -## 6. Deploy Argo Events SA, ClusterRoles, ConfigMap, and Sensor Controller -Note 1: This process is manual right now, but we're working on providing a Helm chart or integrating as a Ksonnet application +## 2. Deploy Argo Events SA, ClusterRoles, ConfigMap, and Sensor Controller +Note 1: This process is manual right now, but we're working on providing a Helm chart or integrating as a Ksonnet application. Note 2: Modify the [argo-events-cluster-roles.yaml](../hack/k8s/manifests/argo-events-cluster-roles.yaml) file to use the correct namespace that you wish to deploy the sensor controller + signal microservices. ``` -$ k apply -f hack/k8s/manifests/argo-events-sa.yaml -$ k apply -f hack/k8s/manifests/argo-events-cluster-roles.yaml -$ k apply -f hack/k8s/manifests/sensor-crd.yaml -$ k apply -f hack/k8s/manifests/sensor-controller-configmap.yaml -$ k apply -f hack/k8s/manifests/sensor-controller-deployment.yaml +kubectl apply -f hack/k8s/manifests/argo-events-sa.yaml +kubectl apply -f hack/k8s/manifests/argo-events-cluster-roles.yaml +kubectl apply -f hack/k8s/manifests/sensor-crd.yaml +kubectl apply -f hack/k8s/manifests/sensor-controller-configmap.yaml +kubectl apply -f hack/k8s/manifests/sensor-controller-deployment.yaml ``` -## 7. Deploy Argo Events Webhook Signal Microservice -Note: You will need to separately deploy the various signal services that you wish to support. +## 3. Deploy Argo Events Webhook Signal Microservice +Note: In order to have a useful cluster for Argo Events, you will need to separately deploy the various signal services that you wish to support. This command installs the webhook signal service. ``` -$ k apply -f hack/k8s/manifests/services/webhook.yaml +kubectl apply -f hack/k8s/manifests/services/webhook.yaml ``` -## 8. Install Argo +## 4. Install Argo Follow instructions from https://github.com/argoproj/argo/blob/master/demo.md -## 9. Create a webhook sensor +## 5. Create a webhook sensor ``` -$ k apply -f examples/webhook-with-resource-param.yaml +kubectl apply -f examples/webhook-with-resource-param.yaml ``` Verify that the sensor was created. ``` -$ kubectl get sensors -n default +kubectl get sensors -n default ``` Verify that the signal microservice is listening for signals and the sensor is active. ``` -$ kubectl logs signal-webhook-xxx -f -$ kubectl get sensor webhook-with-resource-param -n default -o yaml +kubectl logs signal-webhook-xxx -f +kubectl get sensor webhook-with-resource-param -n default -o yaml ``` -## 10. Trigger the webhook & corresponding Argo workflow +## 6. Trigger the webhook & corresponding Argo workflow Trigger the webhook via sending a POST with a JSON with a "message" key and value. Ensure that you set the header "Content-Type" to "application/json" or this event will be ignored. +Note: the `WEBHOOK_SERVICE_URL` will differ based on the Kubernetes cluster. ``` -$ curl -d '{"message":"this is my first webhook"}' -H "Content-Type: application/json" -X POST $(minikube service --url webhook) +export WEBHOOK_SERVICE_URL=$(minikube service --url webhook) +curl -d '{"message":"this is my first webhook"}' -H "Content-Type: application/json" -X POST $WEBHOOK_SERVICE_URL/hello ``` Verify that the Argo workflow was run when the trigger was executed. ``` -$ argo list +argo list ``` Verify that the sensor was updated correctly and moved to a "Complete" phase ``` -$ kubectl get sensor webhook-with-resource-param -n default -o yaml +kubectl get sensor webhook-with-resource-param -n default -o yaml ``` Check the logs of the Argo workflow pod for the message you posted. ``` -$ k logs arguments-via-webhook-event main +kubectl logs arguments-via-webhook-event main ``` Check the logs of the sensor-controller pod or the associated signal microservice if there are problems. \ No newline at end of file