From f2a9f8a93888ef8adb03a32de48b15e212571d48 Mon Sep 17 00:00:00 2001 From: Soam Vasani Date: Fri, 8 Sep 2017 18:35:08 -0700 Subject: [PATCH] Install and upgrade guide updates --- Documentation/docs-site/content/install.md | 57 +++++++++--- .../{kubesetup.md => kubernetessetup.md} | 6 +- .../docs-site/content/upgrade-from-v0.1.md | 90 +++++++++++++++++++ 3 files changed, 138 insertions(+), 15 deletions(-) rename Documentation/docs-site/content/{kubesetup.md => kubernetessetup.md} (88%) create mode 100644 Documentation/docs-site/content/upgrade-from-v0.1.md diff --git a/Documentation/docs-site/content/install.md b/Documentation/docs-site/content/install.md index cb208f14..c964747e 100644 --- a/Documentation/docs-site/content/install.md +++ b/Documentation/docs-site/content/install.md @@ -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. + diff --git a/Documentation/docs-site/content/kubesetup.md b/Documentation/docs-site/content/kubernetessetup.md similarity index 88% rename from Documentation/docs-site/content/kubesetup.md rename to Documentation/docs-site/content/kubernetessetup.md index f96e1ed9..b57a2c5a 100644 --- a/Documentation/docs-site/content/kubesetup.md +++ b/Documentation/docs-site/content/kubernetessetup.md @@ -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. diff --git a/Documentation/docs-site/content/upgrade-from-v0.1.md b/Documentation/docs-site/content/upgrade-from-v0.1.md new file mode 100644 index 00000000..9b34e783 --- /dev/null +++ b/Documentation/docs-site/content/upgrade-from-v0.1.md @@ -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 +``` +