Install and upgrade guide updates

2017-09-08 19:12:16 -07:00
parent 3a0ebdd93b
commit f2a9f8a938
3 changed files with 138 additions and 15 deletions
@@ -1,7 +1,7 @@
 ---
 title: "Fission Installation Guide"
 date: 2017-09-07T20:10:05-07:00
-draft: true
+draft: false
 ---

 Welcome! This guide will get you up and running with Fission on a
@@ -9,8 +9,11 @@ Kubernetes cluster.
           
 ### Cluster preliminaries

+If you don't have a Kubernetes cluster, [here's a quick guide to set
+one up](../kubernetessetup).
+
 Let's ensure you have the Kubernetes CLI and Helm installed and
-ready. If you already have these tools, [skip to the next section](#install-fission).
+ready. If you already have helm, [skip ahead to the fission install](#install-fission).

 #### Kubernetes CLI

@@ -78,23 +81,22 @@ role-based access control.)

 ### Install Fission

-```
-$ helm repo add fission-charts https://fission-charts.github.io
-
-$ helm install --namespace fission fission-all
-```
-
 #### Minikube

-On minikube, you'll need to pass one additional option to the helm
-install command:
-
 ```
 $ helm repo add fission-charts https://fission-charts.github.io

 $ helm install --namespace fission fission-all --set serviceType=NodePort
 ```

+#### Cloud hosted clusters (GKE, AWS, Azure etc.)
+
+```
+$ helm repo add fission-charts https://fission-charts.github.io
+
+$ helm install --namespace fission fission-all
+```
+

 #### Minimal version

@@ -102,7 +104,7 @@ The fission-all helm chart installs a full set of services including
 the NATS message queue, influxDB for logs, etc. If you want a more
 minimal setup, you can install the fission-core chart instead.

-### Install Fission CLI
+### Install the Fission CLI

 #### Mac OS

@@ -125,7 +127,29 @@ this windows executable: [fission.exe](https://github.com/fission/fission/releas

 ### Set environment vars

+Set the FISSION_URL and FISSION_ROUTER environment variables.
+FISSION_URL is used by the fission CLI to find the server.
+(FISSION_ROUTER is only needed for the examples below to work.)

+#### Minikube
+
+If you're using minikube, use these commands:
+
+```
+  $ export FISSION_URL=http://$(minikube ip):31313
+  $ export FISSION_ROUTER=$(minikube ip):31314
+```
+#### Cloud setups
+
+Save the external IP addresses of controller and router services in
+FISSION_URL and FISSION_ROUTER, respectively.  Wait for services to
+get IP addresses (check this with ```kubectl --namespace fission get
+svc```).  Then:
+
+```
+  $ export FISSION_URL=http://$(kubectl --namespace fission get svc controller -o=jsonpath='{..ip}')
+  $ export FISSION_ROUTER=$(kubectl --namespace fission get svc router -o=jsonpath='{..ip}')
+```

 ### Run an example

@@ -144,3 +168,12 @@ $ curl http://$FISSION_ROUTER/hello
 Hello, world!
 ```

+### What's next?
+
+If something went wrong, we'd love to help -- please [drop by the
+slack channel](http://slack.fission.io) and ask for help.
+
+Check out the
+[examples](https://github.com/fission/fission/tree/master/examples)
+for some example functions.
+
@@ -1,7 +1,7 @@
 ---
 title: "Kubernetes Quick Install"
 date: 2017-09-07T20:10:05-07:00
-draft: true
+draft: false
 ---

 This is a quick guide to help you get started running Kubernetes on
@@ -12,7 +12,7 @@ intended to give you something quickly so you can try Fission on it.)

 ## Minikube

-Minikube is the simplest way to run Kubernetes on your laptop.
+Minikube is the usual way to run Kubernetes on your laptop:

 ### Install and start Kubernetes on OSX:

@@ -36,6 +36,6 @@ $ minikube start

 ## Google Container Engine

-You can use [Google Container Engine's](https://cloud.google.com/container-engine/) free trial to
+Alternatively, you can use [Google Container Engine's](https://cloud.google.com/container-engine/) free trial to
 get a 3-node cluster.  Hop over to [Google Cloud](https://cloud.google.com/container-engine/) to set that up.

@@ -0,0 +1,90 @@
+---
+title: "Upgrading from Fission v0.1 to v0.2.x"
+date: 2017-09-08T16:26:29-07:00
+draft: true
+---
+
+## TL;DR
+
+The Fission API has changed significantly in this version.  The new API is incompatible with the
+old one.  The CLI is compatible; if you wrote scripts using it, those should still work.
+
+Below we describe a tool for migrating your state from your old install to the new one.
+
+While this upgrade is going to be disruptive, we're going to do our best to make sure future
+upgrades aren't as bad.
+
+## Why is this so complicated?
+
+For a couple of reasons, we wanted to switch to using Kubernetes resources (ThirdPartyResources
+now, CustomResources in the next release) for storing Fission state: (a) it would allow users to
+avoid management of another database and (b) Fission would fit better into the Kubernetes
+ecosystem.
+
+Concurrently with this change, we were also trying to make our versioning approach less
+opinionated, so it would work with other tools.
+
+Thirdly, we were also enabling build pipelines (v2 Environments).
+
+These changes, especially the difference in versioning approach, made maintaining compatiblity not
+worth the effort at this early stage of the project.
+
+All that said, we want you to know that we care a lot about compatiblity, and we'll be more
+rigorous about it from the beta release onwards.
+
+## How to Upgrade
+
+1. Get the v0.2 CLI
+1. Get your Fission state from your old install
+1. Install v0.2.1
+1. Restore your Fission state
+1. Destroy your old install
+
+### Get the new CLI
+
+```
+curl -Lo fission https://...
+```
+
+### Get Fission state from v0.1 install
+
+```
+fission upgrade dump
+```
+
+This will create a JSON file with all your fission state in the current directory.
+
+### Install the new version
+
+Follow the [install guide](../install), but you will need to ensure your two installs don't
+conflict. To do that, use separate namespaces and ensure nodeports don't conflict.  Install with a
+command similar to this:
+
+```
+helm install fission-all --namespace fission2 --set controllerPort=31303,routerPort=31304,natsStreamingPort=31305,functionNamespace=fission2-function
+```
+
+### Restore your Fission state into Fission v0.2.1
+
+```
+fission upgrade restore
+```
+
+This uses the file created in the first step.
+
+### Verify
+
+How exactly you do this is up to you! But, verify that your new install is working.
+
+### Switch over
+
+If you had exposed fission's router to the outside world, switch over to using the new install's router.
+   
+### Destroy your old install
+
+Once you're no longer using the old install, you can destroy it with:
+
+```
+kubectl delete namespace fission fission-function
+```
+