chore(hackathon): add hackathon pages to community (spinnaker#1772)

First pass of these docs for the first gardening day. We'll iterate as people try it out for this and subsequent gardening days.
dnilasor · Apr 7, 2020 · a0e5c36 · a0e5c36
1 parent d1d2662
commit a0e5c36
Show file tree

Hide file tree

Showing 11 changed files with 412 additions and 1 deletion.
diff --git a/_data/navigation.yml b/_data/navigation.yml
@@ -721,7 +721,21 @@ community:
     url: /community/stats
   - title: Captain's Log
     url: /community/captains-log/
-
+  - title: Spinnaker Gardening Days
+    url: /community/gardening/
+    children:
+      - title: Schedule
+        url: /community/gardening/schedule/
+      - title: Hackathon Logistics
+        url: /community/gardening/hack-logistics/
+      - title: What to Hack
+        url: /community/gardening/what-to-hack/
+      - title: Slack Map
+        url: /community/gardening/slack-map/
+      - title: Dev Environments
+        url: /community/gardening/dev-environment/
+      - title: Prizes
+        url: /community/gardening/prizes/
 news:
   - title: Sign Up
     url: /news/signup

diff --git a/_includes/gardening-schedule.html b/_includes/gardening-schedule.html
diff --git a/community/gardening/Spinnaker-Garden-1C.jpg b/community/gardening/Spinnaker-Garden-1C.jpg
diff --git a/community/gardening/dev-environment.md b/community/gardening/dev-environment.md
@@ -0,0 +1,222 @@
+---
+layout: single
+title:  "Development Environments for Spinnaker Gardening Days"
+sidebar:
+  nav: community
+---
+What's the best environment Spinnaker development? How can you set up your workstation to debug a Spinnaker service?  It depends! Consider these constraints when choosing your strategy:
+
+* __Locally available computing resources__: hosting Spinnaker services is memory intensive.
+* __Access and cost management for public clouds__: Spinnaker can be hosted in the cloud, where you'll pay for resources.
+* __Familiarity with Kubernetes__: you may use Kubernetes tools to manage your Spinnaker environment if you prefer.
+
+# Install Spinnaker
+First things first, to develop Spinnaker, you'll need a Spinnaker instance. To get that, you have options:
+* Install [Minnaker](https://github.com/armory/minnaker), a POC Spinnaker instance that runs in a Linux VM on your local machine, or in the cloud.
+* [Clone and install each Spinnaker service locally.](#classic-local-installation-method)
+* [Install Spinnaker to your Kubernetes cluster](#kubernetes-installation-methods), running in your cloud provider or private cloud of choice. Read more about the [Kubernetes & Docker method](#kubernetes-and-docker-method) below.
+
+## Classic local installation method
+Follow the [Getting Set Up](https://www.spinnaker.io/guides/developer/getting-set-up/) guide to install Spinnaker locally.
+
+## Minnaker method
+If you're not sure which method to choose, we suggest following [these instructions to install Minnaker](https://github.com/armory/minnaker) in your chosen environment. This simplifies installation steps, and uses lightweight Kubernetes [(K3S)](https://k3s.io/) under the hood. Install in a cloud VM or a local Ubuntu 18.04 VM.
+
+### Set up local development environment
+1. Install your IDE. These instructions target [IntelliJ IDEA](https://www.jetbrains.com/idea/download/#section=mac).
+2. Git clone the [Spinnaker service(s)](https://github.com/spinnaker) you will debug or extend.
+3. Open the project in your IDE: File > Open > Select project folder > Click 'OK'.
+4. Build the project:
+   - Open the 'Gradle' window and double-click the 'Build' task under Tasks > Builds.
+
+#### __Next steps IF your Minnaker instance is running in the cloud__
+
+5. [Install NGROK](https://ngrok.com/download), a tunneling service. Run it to create a tunnel from the service to the Spinnaker instance:
+   - Consult the [port mappings reference](/reference/architecture/#port-mappings) to determine which ports to forward. Create tunnels for the service(s) you're running locally.
+   - Execute `ngrok http <service port number>` e.g. `ngrok http 8089` for echo.
+   - Copy the URL in the `Forwarding` output lines.
+6. Configure your Spinnaker instance to use the forwarded NGROK address(es).
+   - Create a `.hal/default/profiles/spinnaker-local.yml` file.
+   - Add service settings, or copy settings from `.hal/default/staging/spinnaker.yml` and delete unnecessary services. Read more on [custom service settings](/reference/halyard/custom/#custom-service-settings).
+   - Change the `baseURL` for the service to the copied NGROK endpoint.
+7. Configure the local service to communicate with the Spinnaker instance.
+   - Copy the kubeconfig from Spinnaker `/etc/spinnaker/.kube/config` to your local machine (e.g. `/tmp/kubeconfig-minnaker`)
+   - Update the kubeconfig clusters.cluster.server address to point to the external endpoint URL as in this snippet:
+
+    ```
+    apiVersion: v1
+      clusters:
+      - cluster:
+          server: ec2-34-223-57-141.us-west-2.compute.amazonaws.com:6443
+    ...
+    ```
+   - Make sure the security group on your VM allows port 6443.
+   - Use `kubectl port-forward` to forward the services required. For example, if running echo locally, you'll need it to communicate with orca and front50:
+  ```
+  kubectl --kubeconfig config-minnaker -n spinnaker port-forward spin-orca-5f47b76f84-bvh98 8083:8083
+  kubectl --kubeconfig config-minnaker -n spinnaker port-forward spin-front50-64ddf796bf-gznqj 8080:8080
+  ```
+8. __Now you're ready to run and debug the service or services!__
+
+#### __Next steps IF your Minnaker instance is running locally__
+5. [Create a kubeconfig for your machine reference](http://docs.shippable.com/deploy/tutorial/create-kubeconfig-for-self-hosted-kubernetes-cluster/).
+   - Create a skeleton kubeconfig and get the certificate for the cluster:
+   `kubectl config view --flatten --minify`
+   - Create a service account for the namespace: `serviceaccount`
+   - Copy the token for the secret associated with the serviceaccount `kubectl describe secret`
+   - Grant the service account - cluster-admin access `clusterrolebinding`
+   - Update the `users.user` section of the `kubeconfig` by replacing `users.user.password` and `users.user.username` to `users.user.token`, where the token value is the secret value associated with the ServiceAccount.
+   - Update the kubeconfig `clusters.cluster.server` address to point to the IP address of Minnaker on local machine:  e.g.  `192.168.123.128:6443`
+   - Consult this example `kubeconfig` for reference:
+    ```
+
+    apiVersion: v1
+    clusters:
+    - cluster:
+        certificate-authority-data: <CAString>
+        server: https://192.168.1.128:6443
+      name: plugin.example.net
+    contexts:
+    - context:
+        cluster: plugin.example.net
+        user: spinnaker-sa
+      name: plugin.example.net
+    current-context: plugin.example.net
+    kind: Config
+    preferences: {}
+    users:
+    - name: spinnaker-sa
+      user:
+        token: <tokenString>
+    ```
+6. Configure your Minnaker instance to forward ports to your local machine (gateway) via spinnaker-local.yml configuration.
+   - Create a `.hal/default/profiles/spinnaker-local.yml` file.
+   - Add service settings, or copy settings from `.hal/default/staging/spinnaker.yml` and delete unnecessary services. Read more on [custom service settings](/reference/halyard/custom/#custom-service-settings).
+   - Change the `baseURL` for the service to the default gateway IP Address including the port, e.g. `http://192.168.123.1:8083` for orca.
+   - Consult the [port mappings reference](/reference/architecture/#port-mappings) to determine which ports to forward.
+7. Configure the local service to communicate with the Spinnaker instance.
+   - The `kubeconfig` you just created does part of the configuration.
+   - Use `kubectl port-forward` to forward the services required. For example, if running Echo locally, you'll need it to communicate with Orca and Front50:
+     - Option 1: Forward via Service:
+        `kubectl` `--``kubeconfig config-minnaker -n spinnaker port-forward svc/spin-orca 8083:8083 &`
+        `kubectl --kubeconfig config-minnaker -n spinnaker port-forward svc/spin-front50 8080:8080 &`
+     - Option 2: Forward via Pod:
+        `kubectl --kubeconfig config-minnaker -n spinnaker port-forward spin-orca-5f47b76f84-bvh98 8083:8083`
+        `kubectl --kubeconfig config-minnaker -n spinnaker port-forward spin-front50-64ddf796bf-gznqj 8080:8080`
+8. __Now you're ready to run and debug the service or services!__
+
+
+
+
+
+## Kubernetes and Docker method:
+
+### Kubernetes installation methods
+_The instructions for this method are in beta. Pull requests welcome!_
+
+1. Install Spinnaker to a Kubernetes cluster. There are several ways to do this:
+   - [Install Halyard in Docker](/setup/install/halyard/#install-halyard-on-docker)
+     - In your `docker run` command, mount the `.kube` directory to the container to allow you to modify `.kube` config files on your local machine and persist the changes inside the container:
+       ```
+       docker run -p 8084:8084 -p 9000:9000 \
+         --name halyard --rm \
+         -v ~/.hal:/home/spinnaker/.hal \
+         -v ~/.kube:/home/spinnaker/.kube \
+         -it \
+         gcr.io/spinnaker-marketplace/halyard:stable
+       ```
+   - Use the [Spinnaker for Google Cloud Engine](https://cloud.google.com/docs/ci-cd/spinnaker/spinnaker-for-gcp) solution, which installs Spinnaker to Google Kubernetes Engine.
+   - Consult the installation guide for [Amazon Kubernetes Service](https://aws.amazon.com/blogs/opensource/continuous-delivery-spinnaker-amazon-eks/)
+   - Use the new [Spinnaker Operator](https://docs.armory.io/spinnaker/operator/#install-operator) to quickly install with `kubectl` commands.
+     - Install the Operator in [cluster mode](https://docs.armory.io/spinnaker/operator/#installing-operator-in-cluster-mode)
+     - Front50 won't start up successfully until you point Spinnaker to persistent storage, such as an S3 bucket. Update `deploy/spinnaker/basic/SpinnakerService.yml` as in this snippet:
+    ```
+    ...
+    spinnakerConfig:
+      config:
+        persistentStorage:
+          persistentStoreType: s3
+          s3:
+            bucket: mybucket
+            rootFolder: front50
+        version: 2.18.0
+    ...
+    ```
+
+2. Open a bash shell in the location where Halyard is installed.
+  - If Halyard is running in Docker, run `docker exec -it halyard bash` to enter a shell.   
+3. Edit the Kubernetes block of your .hal/config with your namespace and kubeconfig file location to enable a Kubernetes install, as in this snippet:
+  ```
+  ...
+  kubernetes:
+    enabled: true
+    accounts:
+      name: kubernetes
+      requiredMembership: []
+      providerVersion: V2
+      permissions: []
+      dockerRegistries: []
+      configureImagePullSecrets: true
+      cacheThreads: 1
+      namespaces:
+        - <namespace>
+      omitNamespaces: []
+      kinds: []
+      omitKinds: []
+      customResources: []
+      cachingPolicies: []
+      kubeconfigFile: </path/to/kubeconfig/>
+      oAuthScopes: []
+      onlySpinnakerManaged: false
+    primaryAccount: kubernetes
+      ...
+  ```
+4. Port-forward the externally-hosted Spinnaker services to your local machine
+  - You may use [NGROK](https://ngrok.com/download)
+  - Or, try this Fish function: `pf-spinnaker` loops through all of the Spinnaker services in your Kubernetes namespaces and forwards their ports to your local machine. Try it:
+  ```
+  function pf-spinnaker
+    set -l services (string split , -- \
+                    (kubectl get services -o json \
+                      | jq -r '.items[] | [.metadata.name, .spec.ports[0].port] | @csv'))
+    set -l service_length (count $services)
+    set -l current_service 1
+    while test $current_service -lt $service_length
+      set -l service (string replace --all '"' '' -- $services[$current_service])
+      set -l port $services[(math $current_service + 1)]
+      command kubectl port-forward "service/$service" $port &
+      set current_service (math "$current_service+2")
+    end
+  end
+  function kill-background
+    jobs | tail -n"+1" | awk -F\  '{print $2}' | xargs -I"{}" kill "{}"
+  end
+  ```
+  To tear down these port forwards (for example, when restarting a service), run this function from the same terminal that issued `pf-spinnaker`:
+  ```
+  function kill-background
+    jobs | tail -n"+1" | awk -F\  '{print $2}' | xargs -I"{}" kill "{}"
+  end
+  ```
+5. Git clone the [Spinnaker service(s)](https://github.com/spinnaker) you will debug or extend.
+6. Hack!
+7. When you're ready to run integration tests, create a docker image with your local build. Read more [in this blog](https://aetas.pl/posts/2019-11-21-docker-image-with-gradle/).
+8. Tag the image and push it to Docker Hub, Artifactory, Docker Registry, or another artifact store.
+9. Edit the [service settings](https://www.spinnaker.io/reference/halyard/custom/#custom-service-settings) for your profile, in `~/.hal/<profileName>/service-settings/<serviceName>.yml`, e.g. `~/.hal/default/service-settings/echo.yml` to pull the container image into your Spinnaker instance:
+  ```
+  artifactId:
+  kubernetes:
+    imagePullSecrets:
+      - artifactory-creds
+  ```
+  Include image pull secrets if the container is in a private repository like Artifactory.
+10. Run `hal deploy apply` inside the Halyard container to deploy your modified version of the service.
+  - If using the `pf-spinnaker` Fish function to port-forward, run the `kill-background` function and then re-reun `pf-spinnaker` each time you restart a service.
+
+__Now you're ready to run and debug the service or services!__
+
+## Additional references
+* [This repository](https://github.com/robzienert/spinnaker-oss-setup) installs all Spinnaker dependencies besides the JDK to your machine running OSX. With a few tweaks and a package manager swap, you could also use it to automate dependency setup on Linux.
+
+## Help us improve the contributor experience
+This page is beta! Please submit a Pull Request, or use the #gardening-feedback channel to share your thoughts on how to improve the Spinnaker contributor experience.
diff --git a/community/gardening/hack-logistics.md b/community/gardening/hack-logistics.md
@@ -0,0 +1,26 @@
+---
+layout: single
+title:  "Hackathon Logistics at Spinnaker Gardening Days"
+sidebar:
+  nav: community
+---
+Here's how we'll garden and hack together. Following these guidelines keeps you eligible for prizes and charitable donations, and sets us up for for maximum community impact.
+
+### Create a team Slack channel
+_Even if you're starting solo_, create a team channel for your project in [Spinnaker Slack](https://join.spinnaker.io). Use the format __#gardening-team-__+_projectString_ with a project string that describes your project and matches your repo name, if applicable.
+
+### Join project matchmaking
+The [Project Matchmaking session](https://armory.zoom.us/j/6807216019) at 8:40 AM PST on Thursday 4/9 will give teams and individuals the opportunity to pitch a project/task and recruit team members. Each spokesperson can take 90 seconds to pitch an idea and invite attendees to a Slack channel to discuss and organize.
+
+### Create repositories
+Starting fresh with some new plugin code, or writing a tutorial? Create all new project repositories in [Spinnaker-Hackathon](https://github.com/spinnaker-hackathon). Name your repo with a descriptive project string that you'll use in your Slack channel name. _Note: Your GitHub handle will be added as a member to the Spinnaker-Hackathon organization after check in. You must check in to receive repository creation privileges. Get the check-in link by joining the [Gardening Central](https://armory.zoom.us/j/6807216019) Zoom room._
+
+### Fork Spinnaker repositories
+Need to fork an existing Spinnaker project(s) to hack? Fork into the [Spinnaker-Hackathon](https://github.com/spinnaker-hackathon):
+![where to fork](/org-fork.png)
+When it's time to submit a pull request, do so from your fork. Read more on [best practices in fork & pull request workflows](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
+
+### Use a Spinnaker staging environment
+When developing a Spinnaker plugin, it's useful to do integration testing in a running Spinnaker instance. This allows you to interact with the frontend. For this event, Armory will provide Spinnaker staging instances running in AWS for project teams to use as needed.
+
+_Look out for more details on how to gain access to a staging instance._
diff --git a/community/gardening/index.md b/community/gardening/index.md
@@ -0,0 +1,32 @@
+---
+layout: single
+title:  "Spinnaker Gardening Days #communityHack"
+sidebar:
+  nav: community
+---
+_Welcome to the command center for Spinnaker Gardening Days, a community celebration and hackathon._
+{%
+  include
+  figure
+  image_path="./Spinnaker-Garden-1C.jpg"
+%}
+## Register
+[Register for Spinnaker Gardening Days](https://www.eventbrite.com/e/spinnaker-gardening-days-communityhack-tickets-97845696111) on Eventbrite to reserve your tickets.
+
+## Jump In!
+To attend Spinnaker Gardening Days, you'll need Zoom. See Zoom's ["Joining a Meeting" documentation](https://support.zoom.us/hc/en-us/articles/201362193-Joining-a-Meeting) to learn how to join.
+
+* Join the [__Gardening Central__ Zoom Room](https://armory.zoom.us/j/6807216019) to enter Spinnaker Gardening Days
+* Join [Spinnaker Slack](https://join.spinnaker.io) to chat in [event & team channels](slack-map.md). Visit __#gardening-general__, our main event channel.
+* [Master schedule](schedule.md)
+* [What to hack](what-to-hack.md)
+* [Hackathon logistics](hack-logistics.md)
+* [Slack map](slack-map.md)
+* [Read about prizes](prizes.md)
+* [Spinnaker-hackathon Github organizaion](https://github.com/spinnaker-hackathon)
+* [Spinnaker Gardening repository](https://github.com/spinnaker-hackathon/gardening)
+
+
+## Guidelines
+1. No hate speech, put-downs, or sexual content allowed in hackathon meetings or channels. Keep it classy and remember, we all have the same intrinsic value.
+2. Don't be afraid to share your thoughts, ask for help in __#gardening-ineedhelp__, or try something new. This is a safe space!
diff --git a/community/gardening/org-fork.png b/community/gardening/org-fork.png
diff --git a/community/gardening/prizes.md b/community/gardening/prizes.md
@@ -0,0 +1,18 @@
+---
+layout: single
+title:  "Prize Information"
+sidebar:
+  nav: community
+---
+_This page is under construction. Look out for more details soon as we validate our contribution data collection strategy!_
+
+Here's the prizing structure (we reserve the right to add mystery prizes to sweeten the deal!):
+  - [Mavic Mini Fly More Kit](https://store.dji.com/product/mavic-mini?vid=84651), a fully-equipped lightweight camera drone
+    - Enter a drawing to win by submitting a PR to a Spinnaker service or project while participating in Spinnaker Gardening
+  - [Click 'N Grow Smart Garden 9](https://www.clickandgrow.com/products/the-smart-garden-9), plus seed quilts, for optimal urban or pandemic gardening
+    - Win by leading a project team and recruiting team members from the community (hint: [start here](https://github.com/spinnaker-hackathon/gardening/wiki/Project-Ideas))
+  - [Sphero Mini](https://www.sphero.com/sphero-mini) programmable robotic ball
+    - Brand-new contributors, win by joining a project team, participating in the demo, and creating one or more contributions (PR/issue comments and issues count!) while participating in Spinnaker Gardening
+  - Win a mystery prize by participating in a project demo : )
+  - Win free lunch delivery, swag, and unlimited smiles
+    - Win by showing up to Spinnaker Gardening
diff --git a/community/gardening/schedule.md b/community/gardening/schedule.md
@@ -0,0 +1,10 @@
+---
+layout: single
+title:  "Master Schedule for Spinnaker Gardening Days #communityHack"
+sidebar:
+  nav: community
+---
+## Schedule
+_This schedule is under construction. Look out for more activities to be added! Everyone is welcome to host an activity for 10 minutes or more. All times and topics that adhere to our guidelines are welcome! Ping in #gardening-general to be added to the schedule._
+
+<iframe style="width:100%; height:4300px; overflow: auto;" src="https://docs.google.com/spreadsheets/d/e/2PACX-1vSt3RH9GlxOrjR7DFJ3VUZPaPkRh9XEnRf5cCd2n7y7HAC6wlf0JVNYXPoYwXu1PZ0NtGzsxu7cPPfi/pubhtml?widget=true&amp;headers=false"></iframe>